Datafeed
Overview of Symphony Messaging Datafeed
Last updated
Was this helpful?
Overview of Symphony Messaging Datafeed
Last updated
Was this helpful?
Deprecation Notice v4/datafeed (known as Datafeed v1) The legacy Datafeed v1 service will no longer be supported on April 30, 2023. Please read for more information on this transition. Please reach out to your Technical Account Manager or to the Developer Relations team for more information.
The Symphony Messaging datafeed provides a stream of real-time messages and events for all conversations that a bot is a member of. Any event that occurs within a bot's scope will be captured and delivered to the bot by the datafeed. The datafeed forms the basis of all interactive and conversational bot workflows as it allows bots to directly respond to Symphony Messaging messages and events.
Symphony Messaging provides a Datafeed API that allows bots to easily and datafeeds.
Once a bot has created a datafeed, it has access to all of the within its scope, acting as a secure channel between a bot and all activity happening in the Symphony Messaging Pod. Additionally, all messages and events within a bot's scope are encrypted by the Agent before reaching your bot. That way the bot is the only one who can access the contents of these events and messages being delivered.
The following illustrates the relationship between your bot, datafeed, and Symphony Messaging's components:
Bot creates datafeed via Symphony Messaging’s REST API
Agent creates secure upstream connection with the Symphony Messaging Pod
End user sends a message to a bot in a chatroom
Pod delivers ‘MESSAGESENT’ event to Agent
Bot reads datafeed via REST API
Agent delivers ‘MESSAGESENT’ event payload to the Bot
Events are delivered to your bot via the datafeed as JSON objects. Each type of Symphony Messaging event corresponds to a different JSON payload.
For example, if a user sends your bot a message, an event of type 'MESSAGESENT' will be delivered to your bot through the datafeed:
Notice how each event returned by the datafeed has important metadata and attributes such as messageId, timestamp, (event) type, initiator, as well as the contents of the message itself inside of the payload object. Additionally, you can find the streamID corresponding to the message and also information regarding externalRecipients.
For a full list of the JSON payloads corresponding to each event type, continue here:
The BDK (Bot Developer Kit) comes bootstrapped with a DatafeedEventService class that handles all of the logic for creating/reading datafeeds via the API, has best practices for maintaining datafeeds, and also provides event handling architecture that makes it easy to orchestrate complex workflows and introduce custom business logic to your bot.
As a bot developer, all you have to do is to implement generic EventHandler classes, passing in a given event type as the type parameter for that class.
The following diagram shows the event handling workflow:
Bot creates datafeed via Symphony Messaging’s REST API
Agent creates secure upstream connection with the Symphony Messaging Pod
End user sends a message to a bot in a chatroom
Pod delivers ‘MESSAGESENT’ event to Agent
Bot reads datafeed via REST API
Agent delivers ‘MESSAGESENT’ event payload to the Bot
Bot routes event to appropriate event listener/handler
Inside of onMessageSent() is where you implement your own business logic such as accessing a database, connecting to an external API, or reply back to your user by leveraging the Symphony Messaging API/BDK methods:
As you can see, the datafeed acts as the backbone of your Bot. In many cases your Bot will be waiting for events to come in through the datafeed, which it constantly 'reads'. When an event or message comes through the datafeed, your bot will 'listen' for the event, extract the relevant data from the JSON payload and kick off its intended workflow.
While you can write all of this datafeed logic yourself, our dedicated BDK toolkits provide out-of-the-box datafeed support and event handling logic making it easy to bootstrap your bot and add custom business logic.
The legacy agent/v4/datafeed API is out of support since April 30, 2023.
To facilitate this transition, a new feature called the datafeed bridge has been introduced in the Agent service so consumers of the deprecated APIs keep a functioning service.
This bridge is available starting with Agent 22.6 (June 2022) and can be enabled through the following configuration flag agent.df1ToDf2Bridge.enabled.
Since Agent release 23.6 (June 2023), this bridge is enabled by default, but could still be disabled through configuration.
Then, starting with Agent release 23.9 (September 2023), the bridge is always enabled.
The v5 endpoints are different from the v4 ones, so migrating requires changes in your code. If you are using our Java BDK, migrating to v5 is a simple configuration change.
Otherwise, the mapping between the API endpoints is the following:
Path /agent/v4/datafeed (deprecated)
Via a POST on the endpoint /agent/v4/datafeed/create, the datafeed is created and then the ID is persisted in a file, which is by default datafeed.id on the bot side
The bot subscribes to this ID to retrieve datafeed events; if it cannot be retrieved by using this ID, a new datafeed is created
Via a GET on the endpoint /agent/v4/datafeed/{id}/read, the list of events within the specific datafeed identified with {id} is returned
Deleting a datafeed is not supported
Path /agent/v5/datafeeds
Via a GET on the endpoint /agent/v5/datafeeds, is returned the list of already created IDs for a service account
Via a POST on the endpoint /agent/v5/datafeeds, the datafeed is created and the ID is not persisted on the bot side → Even if the bot is stale, a GET on the same endpoint will retrieve the ID to which the service account is subscribed
Via a POST on the endpoint /agent/v5/datafeeds/{id}/read with a parameter ackId (empty string at the first query), the endpoint returns: the list of events, a new ackId string → This ackId permits acknowledgement of the last query and retrieve all events since the last one. All events received between the last payload and the new request are queued and therefore retrieved.
Via a DELETE on /agent/v5/datafeeds/{id}, the datafeed specified with the {id} is deleted.
After the DatafeedEventService creates/reads from the datafeed API, it categorizes each event based on its event type seen , and dispatches the event downstream to a generic event handler class. For example, If a user sends a message to bot inside a chatroom, the event will be read by the datafeed, and dispatched downstream to the EventHandler class that that takes MessageEvent in as a type parameter. Further the handle() method belonging to your EventHandler class will be called each type that event type is read by the datafeed.
This has an impact on you if some of your automations or bots are still using this API. Please upgrade to the new APIs.
We encourage you to migrate your bots to use the new . The bridge is a temporary solution, which objective is to facilitate the migration. If you use the BDK in or , the migration between v4 and v5 is automatic. We advise you to take this opportunity to migrate your bots to the BDK if you haven’t done so.
