S
S
Symphony Developers Documentation
Search…
Main
Building Bots on Symphony
Building Extension Applications on Symphony
Developer Certification
Developer Tools
Symphony REST API
Mobile Frameworks
Datafeed
Overview of Symphony Datafeed
Datafeed v1 deprecation notice
The legacy Datafeed v1 service will no longer be supported on April 30, 2023. Please read below for more information on this transition.
The legacy Datafeed v1 service will no longer be supported on April 30, 2023.
This will have an impact on you if some of your automations or bots are still using the Datafeed v1 APIs. Please consider upgrading them to use the new Datafeed v2 APIs.
To facilitate this transition, a new feature called the bridge has been introduced in the Agent service so consumers of the deprecated Datafeed v1 APIs will transparently use the Datafeed v2 service.
- This bridge is available starting with Agent 20.15 (May 2022) and can be enabled through the following configuration flag
agent.df1ToDf2Bridge.enabled. - In a subsequent Agent release, this bridge will be enabled by default, but could still be disabled through configuration (October 2022).
- Then in a subsequent Agent release, the bridge will be always enabled (January 2023).
We encourage you to validate the bridge with your existing bots, or to migrate your bots to use the new Datafeed 2 APIs, which is the preferred option. If you use the BDK 2.0 in Java or Python, the migration between Datafeed 1 APIs and Datafeed 2 APIs is a simple configuration change. We advise you to take this opportunity to migrate your bots to the BDK 2.0 if you haven’t done so, the Developer Relations team can guide you through it.
Please reach out to your Technical Account Manager or to the Developer Relations team for more information.
Overview of Datafeed
The Symphony 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 messages and events.
Datafeed Architecture
Once a bot has created a datafeed, it has access to all of the events within its scope, acting as a secure channel between a bot and all activity happening in the Symphony 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's components:
- 1.Bot creates datafeed via Symphony’s REST API
- 2.Agent creates secure upstream connection with the Symphony Pod
- 3.End user sends a message to a bot in a chatroom
- 4.Pod delivers ‘MESSAGESENT’ event to Agent
- 5.Bot reads datafeed via REST API
- 6.Agent delivers ‘MESSAGESENT’ event payload to the Bot
Real-Time Events
Events are delivered to your bot via the datafeed as JSON objects. Each type of Symphony 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:1
{
2
"id": "9rc1dr",
3
"messageId": "Fd4Pc8xO5Vg6hVfzabFe2X___oyM1eXobQ",
4
"timestamp": 1595365005847,
5
"type": "MESSAGESENT",
6
"initiator": {
7
"user": {
8
"userId": 344147139494862,
9
"firstName": "Reed",
10
"lastName": "Feldman",
11
"displayName": "Reed Feldman (SUP)",
12
"email": "[email protected]",
13
"username": "reedUAT"
14
}
15
},
16
"payload": {
17
"messageSent": {
18
"message": {
19
"messageId": "Fd4Pc8xO5Vg6hVfzabFe2X___oyM1eXobQ",
20
"timestamp": 1595365005847,
21
"message": "<div data-format=\"PresentationML\" data-version=\"2.0\" class=\"wysiwyg\"><p>hi</p></div>",
22
"data": "{}",
23
"user": {
24
"userId": 344147139494862,
25
"firstName": "Reed",
26
"lastName": "Feldman",
27
"displayName": "Reed Feldman (SUP)",
28
"email": "[email protected]",
29
"username": "reedUAT"
30
},
31
"stream": {
32
"streamId": "IEj12WoWsfTkiqOBkATdUn___pFXhN9OdA",
33
"streamType": "IM"
34
},
35
"externalRecipients": false,
36
"userAgent": "DESKTOP-43.0.0-10902-MacOSX-10.14.6-Chrome-83.0.4103.61",
37
"originalFormat": "com.symphony.messageml.v2",
38
"sid": "98202eac-dcf4-4b1e-a120-596db38319dc"
39
}
40
}
41
}
42
}
Copied!
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.Here is the full list of different real-time datafeed events:
Event Type
Description
Message Sent
Generated when a message is sent in an IM, MIM, or chatroom of which the user in context is a member, including messages sent by the user themselves.
Messages Suppressed
Generated when messages are suppressed.
Symphony Elements Action
Generated when a user replies to a bot message that contains an interactive form with UX components such as text fields, radio buttons, checkboxes, person selectors and more.
Shared Wall Post
Generated when either:
- The user in context shares a wall post written by another user.
- Another user shares a wall post written by the user in context.
IM/MIM Created
Generated when an IM or MIM is created with the user in context as a member, initiated either by the user in context or another user.
Room Created
Generated when a room is created by the user in context.
Room Updated Message
Generated when a room of which the user in context is a member is updated, including rooms updated by the user himself.
Room Deactivated Message
Generated when a room of which the user in context is a member is deactivated, including rooms deactivated by the user himself.
Room Reactivated Message
Generated when a room of which the user in context is a member is reactivated, including rooms reactivated by the user himself.
User Requested to Join Room
Generated when a user requests to join a room. Only the user who requested to join the room and the owners of that room will receive this event on their datafeeds.
The
affectedUsers attribute represents the owners of the room.User Joined Room
Generated when a new user joins or is added to a room of which the user in context is a member, including when the user himself joins or is added to a room.
User Left Room
Generated when a user leaves or is removed from a room of which the user in context is a member, including when the user himself leaves or is removed from a room.
Room Member Promoted To Owner
Generated when a user is promoted from a participant to an owner of a room of which the user in context is a member, including when the user himself is promoted to an owner or promotes another user.
Room Member Demoted From Owner
Generated when a user is demoted from an owner to a participant of a room of which the user in context is a member, including when the user himself is demoted to a participant or demotes another user.
Connection Requested
Generated when a connection request is sent, either:
- Sent by the user in context to another user.
- Sent to the user in context by another user.
Connection Accepted
Generated when a connection request is accepted, either:
- Sent by the user in context and accepted by another user.
- Sent by another user and accepted by the user in context.
For a full list of the JSON payloads corresponding to each event type, continue here:
Handling Events
Handling Events using the BDK
Similar to the SDKs, 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.After the
DatafeedEventService creates/reads from the datafeed API, it categorizes each event based on its event type seen above, 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.The following diagram shows the event handling workflow:
- 1.Bot creates datafeed via Symphony’s REST API
- 2.Agent creates secure upstream connection with the Symphony Pod
- 3.End user sends a message to a bot in a chatroom
- 4.Pod delivers ‘MESSAGESENT’ event to Agent
- 5.Bot reads datafeed via REST API
- 6.Agent delivers ‘MESSAGESENT’ event payload to the Bot
- 7.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 API/SDK methods:Java
1
public class Example {
2
​
3
public static void main(String[] args) {
4
// create bdk entry point
5
final SymphonyBdk bdk = new SymphonyBdk(loadFromClasspath("/config.yaml"));
6
7
// create listener to be subscribed
8
final RealTimeEventListener listener = new RealTimeEventListener() {
9
@Override
10
public void onMessageSent(V4Initiator initiator, V4MessageSent event) {
11
log.info("Message sent");
12
}
13
};
14
​
15
// subscribe a listener
16
bdk.datafeed().subscribe(listener);
17
18
// start reading the datafeed
19
bdk.datafeed().start();
20
}
21
}
Copied!
Handling Datafeed Events with SDKs
Symphony SDKs come 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 event listener interfaces that are provided out-of-the-box by Symphony's SDKs. The
DatafeedEventService event service does all of the heavy lifting and acts as the backbone of your bot or workflow.After the
DatafeedEventService creates/reads from the datafeed API, it categorizes each event based on its event type seen above, and dispatches the event downstream to their appropriate event handler function. For example, if a user sends a message to a bot inside a chatroom, the event will be read by the datafeed, and dispatched to the onRoomMessage() function inside the RoomListener Interface.The following diagram shows the event handling workflow:
- 1.Bot creates datafeed via Symphony’s REST API
- 2.Agent creates secure upstream connection with the Symphony Pod
- 3.End user sends a message to a bot in a chatroom
- 4.Pod delivers ‘MESSAGESENT’ event to Agent
- 5.Bot reads datafeed via REST API
- 6.Agent delivers ‘MESSAGESENT’ event payload to the Bot
- 7.Bot routes event to appropriate event listener/handler
Inside of
onRoomMessage() 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 API/SDK methods:Java
Python
Node.js
.NET
RoomListenerImpl.java
1
import clients.SymBotClient;
2
import listeners.IMListener;
3
import model.InboundMessage;
4
import model.OutboundMessage;
5
import model.Stream;
6
​
7
public class RoomListenerImpl implements RoomListener {
8
public void onRoomMessage(InboundMessage message); {
9
OutboundMessage msgOut = new OutboundMessage("Hello " + msg.getUser().getFirstName() + "!");
10
this.botClient.getMessagesClient().sendMessage(msg.getStream().getStreamId(), msgOut);
11
}
Copied!
room_listener_impl.py
1
import logging
2
from sym_api_client_python.clients.sym_bot_client import SymBotClient
3
from sym_api_client_python.listeners.room_listener import RoomListener
4
from sym_api_client_python.processors.sym_message_parser import SymMessageParser
5
​
6
​
7
class RoomListenerImpl(RoomListener):
8
def __init__(self, sym_bot_client):
9
self.bot_client = sym_bot_client
10
self.message_parser = SymMessageParser()
11
​
12
def on_room_msg(self, room_message):
13
logging.debug('Room Message Received')
14
​
15
first_name = self.message_parser.get_im_first_name(room_message)
16
stream_id = self.message_parser.get_stream_id(room_message)
17
​
18
message = f'<messageML>Hello {first_name}, hope you are doing well!</messageML>'
19
self.bot_client.get_message_client().send_msg(stream_id, dict(message=message))
Copied!
1
messages.forEach((message, index) => {
2
let reply_message = 'Hello ' + message.user.firstName + ', hope you are doing well!!'
3
Symphony.sendMessage(message.stream.streamId, reply_message, null, Symphony.MESSAGEML_FORMAT)
4
})
5
}
Copied!
1
public class MyRoomListener : RoomListener
2
{
3
private SymConfig symConfig;
4
​
5
​
6
public void init(SymConfig symConfig)
7
{
8
this.symConfig = symConfig;
9
}
10
​
11
override public void onRoomMessage(Message message)
12
{
13
string FirstCommand = "";
14
string SearchTerm = null;
15
string SearchStatus = null;
16
​
17
if (message.message.Contains("/form"))
18
{
19
string fresponse = "";
20
fresponse += "<form id=\"form_id\">";
21
fresponse += "<text-field name=\"Question_Subject\" required=\"true\" placeholder=\"Ask a Question\" />";
22
fresponse += "<textarea name=\"comment\" placeholder=\"Add details (optional)\" required=\"false\"></textarea>";
23
fresponse += "<button type=\"reset\">Reset</button>";
24
fresponse += "<button name=\"submit_button\" type=\"action\">Submit</button>";
25
fresponse += "</form>";
26
sendMessage(message.stream.streamId, fresponse);
27
}
28
}
29
​
30
private void sendMessage(String streamId, String messageText)
31
{
32
Console.WriteLine("streamId:" + streamId);
33
OutboundMessage message = new OutboundMessage();
34
message.message = "<messageML>"+messageText+"</messageML>";
35
RestRequestHandler restRequestHandler = new RestRequestHandler();
36
string url = "https://" + this.symConfig.agentHost + "/agent/v4/stream/" + streamId + "/message/create";
37
HttpWebResponse resp = restRequestHandler.executeRequest(message, url, false, WebRequestMethods.Http.Post, symConfig, true);
38
​
39
}
40
}
Copied!
​
Conversational Workflow
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 SDKs and BDK provide out-of-the-box datafeed support and event handling logic making it easy to bootstrap your bot and add custom business logic.
Last modified 1mo ago