Chatbots or conversational Bots, are the most common bots in the Symphony Messaging ecosystem. These types of bots run 24/7 and wait for users to initiate conversations in order to perform certain tasks. The conversations could be simple commands or even natural language queries. The bot will determine the user’s intent based on their messages and take the appropriate action.

Chatbot Workflow

1. Kick off your Workflow

As stated before, users can interact with chatbots in chatrooms or 1 to 1 chats. In order to initiate your chatbot's workflow we recommend that users @mention the bot's username in order to get the bot's attention and signal to the bot to begin its intended function. That way, chatbots can be active members of chatrooms, but eliminate noise that is outside the scope of its intended workflow.

It is common for Bots to contain multiple commands or sub workflows that it can action upon. It is best practice to list these commands in a help menu. Additionally, it is best practice for all commands to follow a "/" so that it's clear what text is meant to be processed as a command. The following illustrates these best practices:

2. Listen for Events

A core aspect of all chatbots and conversational bots is the ability to 'listen' to different types of commands and events and reply to them accordingly. The mechanism that enables Bots to listen to events in chats is the Datafeed.

The Datafeed is a real-time message and event stream that can be created using the REST API. The datafeed provides a secure stream of messages and events from all conversations that a bot is in.

In order to 'listen' and respond to user events, bots create a single datafeed and will subsequently have access to all chat activity including non-chat based events such as users being added/removed from chatrooms, external connection requests, as well as chats being created.

To learn more about the Datafeed continue here:

3. Handle Events with Custom Business Logic

The next step of your chatbot workflow is to introduce your custom business logic. Once you have access to the bot's events and messages through the Datafeed, the next step is to create dedicated event listeners. Inside these listeners is where you parse messages, fetch data from external sources, manage conversation state, and make requests to our Symphony Messaging REST API in order to reply to users directly or perform administrative functions such as creating chatrooms.

You can learn more about parsing events and introducing custom business logic here.

Next Steps:

Continue on to our Building a Conversational Bot guide in order to learn more about our development tools and appropriate development pathway for building your first Symphony Messaging Chatbot.

Headless Bots are the simplest form of Bots. Headless Bots usually take the form of a script that is either run on a scheduled basis or triggered by an event from an external system. These scripts are usually transient and terminate after performing their assigned task, like sending an alert or daily digest message.

Headless Bot Workflows

Scheduled Workflow

Often times, Headless Bots run on a scheduled basis. Since Headless Bots do not have a conversational aspect, they do not need to create/maintain a Datafeed. As a result, Headless Bots do not need to always be running.

In practice, each time a Headless Bot kicks off its scheduled workflow, it will:

1. Authenticate

2. Post a message/alert in a designated chat or call any number of API endpoints

3. Terminate its process

External Workflow

Headless Bots can also listen for webhooks or incoming events from external/third-party systems. By listening and handling different events from multiple systems, Headless Bots are able to transform Symphony Messaging into a centralized notification center for all your data.

In practice, a Headless Bot needs to expose an endpoint in order to listen and handle these webhooks or incoming events. Each time the bot receives a webhook or an incoming request, it must also:

1. Authenticate

2. Post a message/alert in a designated chat or call any number of API endpoints

3. Terminate its process

Next Steps:

Continue on to our Building a Headless Bot guide. Here you will learn how to get your own Headless Bot up and running and take a closer look at the APIs used to create a simple Headless Bot workflow:

What is a Bot?

A bot on Symphony Messaging can be thought of as an automated version of a human performing specific tasks in Symphony Messaging chats. Most actions that an end user is able to perform in Symphony Messaging can be performed by a bot as well.

Each bot has a unique identity represented by a service account that has similar features to an end-user account such as a name and avatar.

Symphony Messaging Bots enable end users to benefit from innovative workflows and time-saving automations built on top of the Symphony Messaging platform.

How do Bots create workflows and automations?

The answer lies in Symphony Messaging's open REST API. Once authenticated, Symphony Messaging bots can leverage the APIs that enables bots to execute administrative functions such as creating chatrooms, managing users, and facilitating cross-pod connections. In addition, our APIs allow bots to perform messaging functions such as sending and receiving messages and signals.

For a full overview of the Symphony Messaging REST APIs continue here:

Next Steps

Before you begin your Bot development journey, it is important to consider the following when determining what type of Bot you build:

1. What are the goals of your Bot?

Before building your Bot, it's important that you identify the use cases that this Bot will serve. In other words, identify the ways in which this Bot will increase productivity, add meaningful color to your daily tasks, centralize information, reduce business pain points, and make working simpler for its users. To easily identify valuable use cases, ask yourself the following:

• Are there any tasks in my daily workflow that are recurring and can be automated to assist me in my job?

• Are there numerous sources of information that I check daily that can be centralized inside of Symphony Messaging?

• Are there any tasks in my daily workflow that require manually sifting through large amounts of data?

• Is there tedious data validation or compliance checks that I must perform when dealing with colleagues, clients, customers, or third-party vendors?

• Do I have to manually collect and carefully collate unstructured data from colleagues, clients, customers, or third-party vendors?

If you need additional inspiration, checkout our Symphony Messaging App Directory for examples of what has been built today: https://symphony.com/resource/app-directory/

2. Who is your Bot's target audience?

The type of Bot you build will depend on who is using and interacting with it. To identify your bot's audience, ask yourself the following:

• Are the users of my bot internal or external counter-parties?

• Will the bot be interacting with front-office or back-office employees mostly?

• Is your bot interacting with a technical audience or business audience?

• Will users interact with your bot via the Symphony Messaging Mobile App or on the desktop?

• What languages does your audience speak?

• Will your bot be performing bot-to-bot communication?

The more you understand your audience, the more you can understand their business pain points and in turn develop a better user-experience and bot-based solution.

3. What sort of interactions will your Bot have?

Users can interact with Bots in IMs, group chats, and in chatrooms. Before building your Bot, it's important to identify the types of interactions between users and your Bot:

Will your Bot be sending and receiving messages to and from users?

If so, you are looking to build a chatbot, which is a type of Bot that allows direct user interaction in the form of request/reply. You can learn more about rich chat-based workflows and building chatbots here:

Will your Bot need to collect structured/unstructured data through Interactive Elements forms?

If so, you are looking to build an interactive bot. Interactive bots leverage Elements to collect user data and feedback through forms, textfields, buttons, etc. You can learn more about interactive workflows and Elements here:

Will your Bot act as a notification system, without any chat or request/reply mechanisms?

If so, you are looking to build a headless bot. Headless bots can leverage webhooks or build custom notification handlers and formatters from external systems. You can learn more about headless bot workflows and notification handlers here:

4. What is your Bot's entry point?

Lastly, it's important to clearly define the lifecycle and scope of your bot's workflow:

• What chats will my bot exist in?

• Will these rooms be public, private, broadcast, or external (cross-pod)?

• How can I define the scope of my bot in order to reduce unnecessary noise not relevant to my bot's workflow?

• How can I clearly define the protocol for initiating my bot's workflow?

Continue here for a full list of Bot's best practices to establish Bot parameters, scope, and protocol:

1. Plan Your Bot

Symphony Messaging Bots can leverage the Symphony Messaging REST API to create innovative workflows and timesaving automations. Depending on your desired workflow, there are many different development avenues available for you and your development team. Understanding these different development options and different APIs available is key to creating a successful bot and positive user experience. Learn more about the different types of Symphony Messaging Bots and APIs here:

2. Leverage our Tools

Symphony has built numerous tools in order to streamline Symphony Messaging Bot Development. Our rich suite of developer tools offers centralized configuration and authentication protocols, provides out of the box API bindings, convenient error handling, datafeed management, and ensures that your Bot is built using Symphony's best practices.

Using an ultra simplified configuration and authentication set up, an intuitive message and room control mechanism, new APIs for message templating and workflow activities, developing bots has never been easier.

Learn more about how you can get started with our developer tools here:

3. Authentication

At Symphony, security is always first. In order to leverage Symphony Messaging's robust set of open APIs, your Bot must first authenticate itself. You can learn more about how to authenticate and the different types of authentication here:

4. Add Custom Business Logic

The last step is to add custom business logic to your Bot. Begin learning about the capabilities of Symphony Messaging REST APIs and bring your workflows and automations to life:

5. Become a Certified Developer

Want to take your Bot building to the next level? Symphony offers a free course and certification program for Developers wishing to improve their Symphony Messaging skills, technical knowledge, and expertise. Learn more about how you can become a Certified Developer today!

Interactive Bots are a form of Chatbot where the conversational flow is driven by interactive Elements forms. Instead of listening for plain text as the only source of data, Interactive Bots can collect data or commands through structured forms.

Elements allow bots to send messages that contain interactive forms with pre-designed text fields, dropdown menus, person selectors, buttons and more. Additionally, Elements reuse Symphony Messaging UX component libraries, enabling developers to easily create interactive bot messages that look and feel like they belong in Symphony Messaging.

To learn more about Elements navigate here:

Interactive Bot Workflow

1. Kick off your Workflow

Users can interact with chatbots in chatrooms and 1 to 1 chats. In order to initiate your Interactive Bot's workflow we recommend that users @mention the bot's username in order to get the bot's attention and signal to the bot to begin its intended function. That way, bots can be active members of chatrooms, but eliminate noise that is outside the scope of its intended workflow.

It is common for bots to contain multiple commands or sub workflows that it can action upon. It is best practice to list these commands in a help menu. Additionally, it is best practice for all commands to follow a "/" so that it's clear what text is meant to be processed as a command. The following illustrates these best practices:

2. Listen for Events

A core aspect of all Interactive Bots is the ability to 'listen' to different types of commands and events and reply to them accordingly. The mechanism that enables Symphony Messaging Bots to listen to events in chatrooms and IMs is the Datafeed.

The Datafeed is a real-time message and event stream that can be created using the REST API. The datafeed provides a secure stream of messages and events from all conversations that a bot is in.

In order to 'listen' and respond to user events, bots create a single datafeed and subsequently have access to all chatroom activity including non-chat based events such as users being added/removed from chatrooms, external connection requests, and chatrooms IMs being created.

To learn more about the Datafeed continue here:

When an end-user submits an Elements form, the bot is able to access the contents of that form through the Datafeed. The Elements form lifecycle is illustrated below:

First an Interactive Bot sends a messageML message containing an Elements form:

After the user fills out their information and clicks the 'Submit' button, the following payload is captured by the Datafeed and delivered to the bot:

3. Handle Events with Custom Business Logic

The next step of your Interactive Bot workflow is to introduce your bot's custom business logic. Now that you have access to the bot's events, messages, and elements payloads through the Datafeed, the next step is to create dedicated event listeners. Inside these listeners is where you parse messages and datafeed payloads, fetch data from external sources, manage conversation state, and make requests to Symphony Messaging REST APIs in order to reply to users directly or performs administrative functions such as creating chatrooms.

Next Steps:

The Symphony Messaging Generator creates a basic configuration file that assumes a fully cloud-hosted Symphony Messaging pod architecture. In this scenario, the pod, key manager and agent are all hosted on the same domain e.g. develop2.symphony.com. If your pod architecture is different and you have other connectivity requirements like a network proxy, you will need to add those options to your configuration file.

host: develop2.symphony.com
bot:
  username: bdk-bot
  privateKey:
    path: rsa/privatekey.pem

bdk:
  host: develop2.symphony.com
  bot:
    username: bdk-bot
    privateKey:
      path: rsa/privatekey.pem

Basic Configuration Structure

Datafeed Configuration Structure

Retry Configuration Structure

An example customized configuration file is seen below:

scheme: https
host: localhost.symphony.com
port: 8443

pod:
  host: dev.symphony.com
  port: 443

agent:
  context: agent

keyManager:
  host: dev-key.symphony.com
  port: 8444

sessionAuth:
  host: dev-session.symphony.com
  port: 8444

bot:
  username: bot-name
  privateKeyPath: path/to/private-key.pem
  certificatePath: /path/to/bot-certificate.p12
  certificatePassword: changeit

ssl:
  trustStorePath: /path/to/all_symphony_certs_truststore
  trustStorePassword: changeit

app:
  appId: app-id
  privateKeyPath: path/to/private-key.pem

datafeed:
  version: v2
  retry:
    maxAttempts: 6
    initialIntervalMillis: 2000
    multiplier: 1.5
    maxIntervalMillis: 10000

retry:
  maxAttempts: 6
  initialIntervalMillis: 2000
  multiplier: 1.5
  maxIntervalMillis: 10000

The Symphony Messaging REST API acts as a secure interface between your Symphony Messaging Bot and Symphony Messaging's components. Symphony's architecture for bots comprises three components: the Symphony Messaging Pod, the API Agent and the Key Manager.

The Symphony Messaging REST API is spread out across these components according to the type of API being called.

API Swagger files

The API Swagger files are available here.

There is one sub-folder per API collection, and each API collection is split in two swagger files: one for the supported endpoints and a second one listing only the deprecated endpoints (e.g. /pod/pod-api-public-deprecated.yaml).

Depending on your pod or agent version, a newly introduced endpoint may not yet be available to you. You can spot these new endpoints as they are tagged with the x-since attribute. For example, an endpoint flagged as x-since: 20.15 will not be present if you are still on SBE 20.14.

REST API Architecture

To learn more about how bots securely interact with Symphony Messaging's three components, continue onto the REST API Architecture guide below:

Pod API

To learn more about how bots can make authentication and administrative calls such as manage streams, manage users or facilitate cross-pod connections, continue onto the Pod API guide below:

Key Manager API

To learn more about how bots can authenticate and encrypt messages on Symphony Messaging, continue onto the Key Manager API guide below:

Agent API

To learn more about how bots can send and receive encrypted messages on Symphony Messaging, continue onto the Agent API guide below:

REST API Reference

For the full Symphony Messaging API reference continue here:

In order to create a bot and begin your development journey, you must first create a bot user, also known as a service account. You can only do this yourself if you are a pod administrator on your Symphony Messaging pod. Otherwise, please seek assistance from your pod administrator or your internal IT Service Desk if you are unsure who to contact.

Create a Bot User

1. Navigate to your Symphony Messaging Admin Portal for your Pod

For example, https://mycompany.symphony.com/?admin

2. Select Create an Account in the left navigation pane

3. Select the Service Account tab

4. Fill in your bot information

The bot username here has to match the username supplied by a bot configuration file exactly.

5. Fill in the RSA Public Key

Paste the entire contents of the public key in the Authentication section. This public key has to match the private key supplied by a bot. If you are unsure how to generate an RSA key pair, use the Symphony Messaging Generator.

6. Set roles and entitlements

Enable the required roles that your bot requires.

Enable the required entitlements that your bot requires.

7. Confirm Bot Creation

The Symphony Messaging Pod API is used to build tools in order to manage and administer Symphony Messaging for your organization. The following guide includes API collections that exist on the Pod:

If successful, the Pod API returns a Session Token which is valid for up to two weeks. This Session Token must be passed along with every subsequent Pod API request. You can read more about Authentication and Token management here:

The User APIs query and manage users on the Pod. These APIs can be used to do the following:

• Search users

• List all users

• Create users

• Update user information

• List user features

• Add/Remove user roles

• List user roles

• List user audit trail

The Stream APIs create and manage IMs and chat rooms. These APIs can be used to do the following:

• Create IM

• Create chatrooms

• Search for rooms

• Get room info

• Deactivate room

• List room members

• Add/Remove room members

• Promote/Demote user to room owner

The Connection APIs manage user connections. These APIs can be used to do the following:

• Get connection

• List connections

• Create connections

• Accept connection

• Reject connection

• Remove connection

The Presence APIs manage presence status for users. These APIs can be used to do the following:

• Get/Set user presence

• Get all users presence

• Register presence interest

• Create presence feed

• Read presence feed

• Delete presence feed

The Symphony Messaging Agent is responsible for encryption and decryption of messages and content sent to and from a bot. As a result, the Agent API is used to build applications that send and receive messages and content. The following guide includes API collections that exist on the Agent:

The Message APIs create, read and search messages on the Pod. These APIs can be used to do the following:

• Get messages

• Create messages

• Get attachments

• List attachments

• Import messages

• Suppress messages

• Search messages

• Get message status

• List message receipts

The Datafeed APIs create and manage real-time event streams from the Pod to your bot. These APIs can be used to do the following:

• Create Datafeed

• Read Datafeed

For more information on how Symphony Messaging Datafeeds allow your bot to create rich and interactive workflows, navigate here:

The Signal APIs create and manage tailored alerts based on mention or tag criteria. These APIs can be used to do the following:

• List signals

• Get signal details

• Create a signal

• Subscribe/Unsubscribe to a signal

• List signal subscribers

This group of APIs perform testing and obtain diagnostics regarding the health of Symphony Messaging components. These APIs can be used to do the following:

• Perform a component health check

• Obtain Agent Info

• Perform an echo test

• Get session info

The Symphony Messaging Key Manager API's sole purpose is to authenticate a bot or API caller with the Key Manager.

If successful, the Key Manager API returns a Key Manager Token which is valid for up to two weeks. This Key Manager Token must be passed along with every subsequent Agent API request in order to encrypt/decrypt messages on the Agent server. You can read more about Authentication and Token management here:

This page lists the available roles and the associated privileges that may be required for certain endpoints:

Individual Role

User Provisioning Role

Scope Management Role

Content Management Role

Expression Filter Policy Management Role

Audit Trail Management Role

Group Manager Role (Distribution List)

Malware Scan State User Role

Malware Scan Manager Role

In order for bots to access the Symphony Messaging REST API and other Symphony Messaging resources, bots must first authenticate.

As we learned in Overview of Pod API, bots must be authenticated on the Pod in order to access Pod API endpoints. To make authenticated Pod API calls, bots must pass a valid Session Token as a header of each Pod API request.

We also learned in Overview of Agent API, that bots must be authenticated on the Key Manager in order to access Agent API endpoints. To make authenticated Agent API calls, Bots must pass a valid Session Token and Key Manager Token as headers of each Agent API request.

In order to obtain a valid Session Token and Key Manager Token, bots must call the Session Authenticate endpoint on the Pod and Key Manager Authentication endpoint on the Key Manager.

RSA Authentication Workflow

We recommend that bots follow the RSA authentication workflow in order to obtain valid Session and Key Manager Tokens:

Certificate-Based Authentication Workflow

For users that do not want to use RSA Authentication, bots can perform certificate-based authentication in order to obtain valid Session and Key Manager Tokens:

Symphony Messaging REST API is spread out over three main components: the Pod, API Agent and Key Manager. Let's take a closer look at these components below.

The Symphony Messaging Pod is a dedicated Symphony Messaging instance for each customer environment. It is a cloud-hosted component that handles all core operations necessary to provide the Symphony Messaging service to you. Since Symphony Messaging provides end-to-end encrypted messaging, all messages passed from user to user are fully encrypted at the time of sending, such that no Pod ever has access to the unencrypted contents of any message.

In addition, the Symphony Messaging Pod provides REST API endpoints in order for your bot to perform administrative functions on the Pod. You can read more about the Pod API here:

API Agent

The API Agent is the component responsible for encrypting and decrypting content sent from and to a bot. The Agent provides REST API endpoints that allow a bot to send and receive encrypted messages, acting as the intermediary between a bot and the Symphony Messaging Pod. In order to safely encrypt and decrypt these messages, the Agent server interacts the Key Manager which provides the keys used for encrypting and decrypting messages.

Read more about the Agent API here:

Key Manager

The Key Manager generates and stores encryption keys which are used to encrypt and decrypt messages by the Agent Server. The Key Manager provides an authentication API that provides a unique Key Manager Token to a calling bot. This token is used to encrypt/decrypt messages on the Agent Server.

Read more about the Key Manager API here:

Interacting with the Components

The three components above all interact with each other in order to create Symphony Messaging's secure messaging service. Let's take a closer look at the sequence of API calls a bot must make in order to send and receive encrypted messages on Symphony Messaging.

The sequence of API calls and component interaction is illustrated below:

• 1. First, a bot must authenticate with the Pod. It does so by calling the Session Authenticate endpoint.

• 1a. If successful, the bot will receive a valid Session Token. This Session Token must be passed along with all subsequent Symphony Messaging API requests destined for the Agent or the Pod.

• 2. Next, a bot must authenticate with the Key Manager. It does so by calling the Key Manager Authenticate endpoint.

• 2a. If successful, the bot will receive a valid Key Manager Token. This Key Manager Token must be passed along with all subsequent Symphony Messaging API requests destined just for the Agent.

• 3. If the bot wants to send a message, the bot will call the Create Message endpoint on the Agent API and pass both Session Token and Key Manager Token as a part of the request.

• 4. At this point, the Agent Server calls the Key Manager and requests the bot's encryption keys.

• 5. Next, the Agent Server validates the bot's Key Manager Token.

• 6. If successful, the Agent will encrypt the payload sent by the bot and will forward the encrypted message up to the Pod where it will be routed to the intended user or chatroom. The message will remain encrypted until it reaches its final destination.

For an even more detailed explanation, enroll in our Developer Certification Program:

On-Premise Deployment

For our enterprise customers, the API Agent and Key Manager components are deployed on-premise, while the Pod is always deployed in the cloud. Your bot or REST API caller is an application that must be deployed on-premise in this scenario.

An visual representation showing an on-premise deployment of Symphony Messaging components is shown below:

In-Cloud Deployment

For our smaller customers, the API Agent and Key Manager may be co-hosted with the Pod in the cloud. Your bot or REST API caller can either be deployed on-premise or in your own cloud environment.

A visual representation showing an in-cloud deployment of Symphony Messaging components is shown below:

Here you will learn about all the ways to streamline work using integrated bots and apps. By leveraging Symphony Messaging's open APIs, developers can create innovative Bots and workflows, save time with strategic automations, and customize their Symphony experience by building third-party Extension Apps.

Keep reading to learn about core Symphony Messaging concepts in order to ensure a smooth development journey from your first line of code to putting your application in production.

Getting Started

It's time to get started. Navigate to one of the following guides to kick off your developer journey today!

• Building Bots on Symphony Messaging

• Building Extension Applications on Symphony Messaging

• Become a Certified Developer

• Developer Tools

• REST API Reference

• Extension API Reference

• Embedded Modules

Begin your development journey by taking an in depth look at Symphony Messaging Bots. Understand the core concepts and all the details needed to get your Bot up and running!

Want to build your first bot together with the Developer Relations team? Head over to our developer training centre and register for our online courses to get started, and it's free.

• Developing Bots using BDK for Java

• Developing Bots using BDK for Python

• Implementing Workflows with WDK

Bring customized and extensible workflows into Symphony Messaging through Extension Apps. Understand how to build, deploy, and manage your Extension App!

Enroll in our brand new Developer Certification program and obtain sandbox access for free! Register and enroll today!

In depth documentation and reference guide for the Symphony Messaging REST API:

In depth documentation and reference guide for the Symphony Messaging Extension API:

Check out our dedicated SDKs, Bot Developer Kit, Bot Generators and more to streamline your development process!

Securely embed stand-alone Symphony Messaging chat modules inside other websites and applications:

Message API endpoints

Bots in Symphony Messaging can use the following API endpoints to create, update and suppress messages in Symphony Messaging chats:

• Message creation via the Create Message v4 endpoint

• Message creation in multiple conversations using the Blast Message endpoint

• Message update via the Update Message endpoint. Note this functionality is not supported on Mobile. On Mobile, updates will appear as new messages instead of replacing the actual message. Also, note the rules and limitations explained in the endpoint specifications documented here.

• Message suppression via the Suppress Message endpoint

Please see below a quick animation showing a simple lifecycle of a bot message in Symphony Messaging with a message created by the bot, updated three times, and then finally suppressed.

Overview of the Message Flow

In the Symphony Messaging message flow, messages are represented in the following markup language forms:

• MessageML: A tag-based language that is a subset of XHTML. MessageML allows templating in Apache Freemarker.

• PresentationML: MessageML translated into the equivalent XHTML tags so it can be rendered and processed by any HTML client.

• ExtensionML: PresentationML translated to a special markup for use by a front end app to perform custom rendering of an entity.

MessageML Render bot

The MessageML Render bot is a productivity tool that helps developers to create chat messages compliant with Symphony Messaging’s message markup language. Using the Render bot, you can get an overview of our message format capabilities, and quickly iterate on the format of a message while previewing the display.

The Render bot is available directly on Symphony Messaging. If this link doesn't work, you can look for MessageML Render bot in the directory.

Diagram of Symphony Messaging Message Flow:

The above diagram shows the following:

1. Your bot uses the Agent API to send messages in MessageML.

2. The Agent API encrypts the messages, and converts them to PresentationML where they are stored in Symphony Messaging 's data store.

3. The Symphony Messaging Datafeed delivers messages to end users or to the Desktop Application as PresentationML.

4. When Bot's retrieve messages via the API, the messages are delivered as PresentationML.

Message Identifiers:

Each message in Symphony Messaging has a unique message ID.

To find the message ID:

• In the Symphony Messaging web or desktop client, click the message timestamp. The Message Status module overlay opens. The message ID is shown in the overlay footer:

• When a message is created via the API, a messageID is returned in the response.

Encoding:

• The message ID in the UI is in standard Base64 encoding.

• Message IDs returned in API responses are in URL Safe Base64 encoding.

• A message ID used in a URL should be in URL Safe Base64 encoding.

• To obtain the URL Safe Base64 conversation (stream) ID, replace forward slashes with underscores, replace pluses with minuses, and ignore any trailing equal signs.

Message Size Limits

Messages may include:

• Maximum 80 entities (tags and mentions).

• Maximum 2,500 unique tokens (distinct words) in the markdown representation of the message.

• 81,130 characters of the encrypted markdown representation of the message. This corresponds approximately to 60,000 characters before encryption. Note that there is a greater chance of reaching the token or the entity limit than the character limit.

• The size of a message cannot exceed 1.5Mb, including both the messageML (message property) and the entityJSON (data property)

{
message=Limit message-content-max-total-size reached, 
status=PAYLOAD_TOO_LARGE, 
code=LIMIT_MESSAGE_CONTENT_MAX_TOTAL_SIZE_REACHED
}

Message Delivery for External Rooms (Cross-Pod)

In the Symphony Messaging architecture, messages are stored in each company data store. When messages are sent externally (for example in External rooms), the messages are copied and transferred from one company to the other using the Amazon AWS SQS service At-least-once Delivery mechanism with Amazon AWS SQS. Amazon AWS SQS service ensures high availability through redundancy, with "At-least-once delivery" guarantee. This means that on very rare occasions, a message can be received more than once.

If this occurs, you might receive a second copy of that message. Therefore, Bots designed to work with External rooms (cross pod) should be idempotent: they should not be affected adversely when processing the same message more than once. Continue here to learn about how your bot should handle duplicate messages.

The following events are returned when reading from a real time messages and events from the datafeed:

All events follow the structure below:

• id: A randomly generated ID for the event, distinct from the ID of the message or chatroom or other objects that the event pertains to. These IDs are unique, except in the situation where two activities are performed simultaneously in the Symphony Messaging client (for example, members are added during the creation of a room). In this case, the two associated events will share the same id. This is for Symphony Messaging internal use.

• timestamp: The timestamp for when the event occurred in Unix timestamp milliseconds format. For certain events, this will be equivalent to the created timestamp of the object the event pertains to (for instance, room creation timestamp).

• type: The type of event that occurred (for instance, a "MessageSent" or "RoomCreated" event).

• initiator: The actor that initiated the event. Currently, initiator will always be a user. The initiator user may be distinct from the affected user (for instance, when one user adds another user to a chatroom).

• payload: An object containing event-specific information that is keyed off the event type.

Message Sent

Generated when a message is sent in an 1-1 chat or chatroom of which the user in context is a member, including messages sent by the user him/herself.

Events attributes details:

• version: version of the message payload, set when the message was created

• message: the message itself

• attachments: list of attachments to the message, not present if there are no attachments

• user: author of the message

• externalRecipients: indicates whether that message is sent to external users.

  • false: the message was only sent to users internal to the company.

  • true: the message was sent to at least one user outside of the company.

• stream: stream the message was posted into.

  • streamId: identifier for the stream.

  • streamType: stream type can be ROOM, IM (1-1 chat), MIM (deprecated), or POST.

• data: JSON structure contained inside an escaped string, NOT an actual JSON structure.

Messages Suppressed

Generated when messages are suppressed:

Symphony Messaging Elements Action

Shared Wall Posts

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 Created

Generated when an IM (1-1 chat) 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 him/herself:

Room Deactivated Message

Generated when a room of which the user in context is a member is deactivated, including rooms deactivated by the user him/herself:

Room Reactivated Message

Generated when a room of which the user in context is a member is reactivated, including rooms reactivated by the user him/herself:

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. Available in Agent 2.56.0.

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.

Generic System Event

Generic System Event is a new category of generic real time event, that is generated in various situations, such as phone calls, events specific to federated chats, and more.

The event is generic, and its structure depends on the event's subtype (genericSystemEvent.eventSubtype).

Most generic events are related to internal processes and are not useful for Bots, so you can just ignore them. When Symphony introduces events that can be relevant to Bots, they will be documented in this page.

The common structure to all Generic System Events is described below. The parameters section will vary depending on the subtype of the event.

Overview of Datafeed

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.

Datafeed Architecture

The following illustrates the relationship between your bot, datafeed, and Symphony Messaging's components:

1. Bot creates datafeed via Symphony Messaging’s REST API

2. Agent creates secure upstream connection with the Symphony Messaging 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 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:

Handling Events using BDK

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:

1. Bot creates datafeed via Symphony Messaging’s REST API

2. Agent creates secure upstream connection with the Symphony Messaging 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 Messaging API/BDK methods:

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 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.

Deprecation notice of Legacy Datafeed API

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.

Changes required to upgrade to v5 endpoints

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

A Stream is like a container for messages exchanged between two or more users via a given 1 to 1 chat (IM) or chat room.

On the Symphony Messaging web or desktop client, this ID can be found by clicking on the timestamp of any message in the conversation. This will open the Message Status module, where the Conversation ID can be found, as shown in the following picture.

The Conversation ID in the Symphony Messaging Web Client is in Standard Base64 encoding and need to be converted to be URLSafe. Conversation IDs returned in API responses are already URLSafe Base64 encoding.

The following list shows the existing endpoints:

This pages describes the implementation of certificate-based Authentication. For the API reference of Certificate Session Authenticate and Certificate Key Manager Authenticate, see the following API endpoints:

Overview of Certificate-Based Authentication

Symphony Messaging allows you to authenticate on the Pod and Key Manager with a client certificate that is signed by a trusted root certificate. When a bot calls the Session Authenticate endpoint, the Pod examines the client certificate provided in the TLS session to identify the bot user and return a Session Token. The same process occurs when a bot authenticates on the Key Manager.

All Symphony Messaging network communications take place over TLS-protected HTTP. The network uses authentication methods that require a client-authenticated TLS connection.

Client certificate authentication in TLS is configured at the port level. Two distinct ports are required for client-authenticated and non-client-authenticated connections. The web and mobile endpoints listen on port 443 (the default port number for HTTPS connections). The API endpoints require a separate port, typically port 8444.

Summary

1. The Admin upload a Signing certificate or Root certificate using the Admin portal.

2. The Admin provides to the developer a child client certificate derived from the Signing or Root certificate

3. The developer authenticates the Bot using the client certificate.

Note: It is also possible to directly upload a Client certificate in the Admin portal instead of a Signing or Root certificate.

1. Upload a Signing Certificate or Root Certificate

Once you have obtained a copy of your Root Certificate Authorities (CA) Public "Signing Certificate", you can upload it using the following steps:

2. Once logged in click the Manage Certificates button then select Import

3. Drag and drop your Certificate file into the popup window:

1. Once you have uploaded the certificate file, click Import. If successful you will receive a confirmation message saying that the certificate has been uploaded successfully.

2. Generate a Client Certificate

You can use the following commands to generate the service account certificate. The certificate must use 4096 bits length.

• USERNAME = Service account username

• PASSWORD = Service account key password

• CA_CERT = CA certificate file

• CA_KEY = CA key file

• CA_PASSWORD = CA key password

• OUTPUT_PASSWORD = PKCS12 file password

Creating a Certificate Signing Request (CSR):

The following table shows the information you will need to provide to your PKI team:

Creation of the service user in the Admin Portal

The Symphony Messaging Admin then creates a service user with a username that matches the Common Name of the certificate, as you can see in the example below:

3. Authenticate

A successful response:

A successful response:

Pass the Session Token and Key Manager Token as headers for all subsequent API requests.

Tags

MessageML supports the following tags for grouping information within a message:

Examples

Here after you can find an example of a message sent by a bot and containing these content grouping tags as well as the structure of the messageML sent:

Please note that you can use content grouping tags mixed with other messageML tags such as Interactive Elements Forms. See the following example including forms in expandable-cards.

Introduction of the MessageML

When calling API methods that create messages, the content of the message must be sent using MessageML markup. MessageML is a tag-based language that is a subset of XHTML, with the addition of tags specific to Symphony Messaging for embedding information (e.g. a mention) into a message.

You can find the specifications of the MessageML language in the attached subpages. Even if they are grouped in different categories for documentation clarity purposes, please note you can do your own mix, respecting the specific rules explained at each component specification level.

Also, please note that messages in MessageML markup are enclosed in a <messageML> tag.

MessageML has full unicode support and messages should be sent using UTF-8 character encoding.

Tags

MessageML supports the following tags to embed media into messages:

Rules and Limitations via an example

For the following examples, we are sending an SVG image along with the message.

Note that an admin user might have to enable the sending of some specific file types. To do that, go to AC Portal >> Company Settings >> Edit Entitlements >> File Types.

Examples

Here after you can find an example of a message sent by a bot and containing an inline image as well as the structure of the messageML sent:

Tags

MessageML supports the following tags to arrange information within a message using tables:

Examples

Here after you can find an example of a message sent by a bot and containing table tags as well as the structure of the messageML sent:

Tags

MessageML supports the following tags for formatting content within a message:

Examples

Here after you can find an example of a message sent by a bot and containing these formatting and semantics tags as well as the structure of the messageML sent:

Versions and Compatibility

Symphony Messaging Elements Forms enable bots to send messages that contain interactive forms with pre-designed text fields, dropdown menus, person selectors, buttons and more. This allows bots to interact with users in a very easy and guided way.

By reusing our pre-designed standard UX component libraries, Elements provide developers with out-of-the-box tools to easily create interactive bot messages that look and feel like they belong in Symphony Messaging. To use the Elements, you just need to call the Create Message endpoint with your bot, using the MessageML format.

Here after, you will find a brief introduction of how to send Elements, then an update of the message flow for Elements, and finally the form specifications.

Sending Elements

To start using Symphony Messaging Elements, you first need to create a form element using the <form> MessageML tag. The form element can be considered the "frame" of a message, containing elements that will be sent by the bot and subsequently read by the datafeed.

You can see below an example of how a user can interact with a form that was sent by a bot, as well as the messageML structure of the message that was sent by the bot, and the payload that is generated and therefore delivered to the bot via the datafeed, containing the information completed and submitted by the user. Please use the tabs to navigate between these 3 documents.

To begin leveraging Symphony Messaging Elements in your bot workflows continue onto our Available Elements that you can find in the subpages.

Message Flow (for Forms)

Every message exists as part of a flow, in a continuum of events that results in user interaction.

Here is that flow in colorful diagram form, for you to know more about each stage of the message:

1. A Bot sends a message with Symphony Messaging Elements in a form

2. The message/from is visible to users. Users interact with the elements

3. Once submitted, the data is submitted to the bot

4. Bots can access the data, by reading the datafeed.

Form specification

MessageML Tag

Forms are represented by the <form> tag, as you can see in the examples above.

Attributes

Rules and Limitations

• The form element can be considered the "frame" of a message, containing elements that will be sent by the bot and subsequently read by the datafeed.

• To be considered valid, the form tag must contain at least one action type "Button" as a child. For more information, refer to Buttons.

• All of the data within a form element will be sent to a bot via the datafeed when a user clicks one of the action buttons in that form. The name attribute of the button will be the value of the action field within the datafeed payload. That way the bot manager can know which button triggered the submission of that form. Starting with Agent 23.11, the auto-submit feature allows to submit the form with a TextField, or with a DropDown Menu.

• If there is more than one element in the form having the same name attribute, the value is converted to an array. Every index of the array is related to a specific element value. The index order is not guaranteed, so the developer needs to iterate through this array and collect the values.

• When a form is submitted and multi-submit attribute is not specified, all the elements within it will be disabled, not being possible to edit or resend the same form. However, if the page is refreshed, the user can fill out the form again and submit it as a new form.

• The attribute multi-submit allows the us to submit the form several times even without needing to refresh the page. It can take 2 different string values:

  • reset which resets the form to the default value when enabling it again for the user,

  • no-reset which keeps the values that were submitted by the user when enabling it again for the user.

• When designing forms, it is important to consider the message size limit. For more information refer to Message size limits.

Examples

The following example shows three forms being used as follows:

• The first form (default) shows how Symphony Messaging users interact with a form, and how the Elements are disabled once the form is submitted.

• The second form (multi-submit-reset) shows how to create a form that can be submitted several times and which resets all its Elements to their default value once the user submits it. You note the Elements are first disabled while loading, then the button shows the user the form has been submitted, before the form is enabled back to its default value for the user to submit it again.

• The third form (multi-submit-no-reset) shows how to create a form that can be submitted several times and which keeps last submitted values once the user submits it. You note the Elements are first disabled while loading, then the button shows the user the form has been submitted, before the form is enabled back to its last submitted value for the user to submit it again.

<messageML>
  <form id="default">
    <text-field name="test"> This form becomes disabled once submitted</text-field>
    <button name="default">Submit</button>
  </form>
  <hr/>
  <form id="multi-submit-reset" multi-submit="reset">
    <text-field name="test" label="Resets values to default"> This form can be submitted more than once</text-field>
    <button name="multi-submit-reset">Submit</button>
  </form>
  <hr/>
  <form id="multi-submit-no-reset" multi-submit="no-reset">
    <text-field name="test" label="Keeps last submitted values"> This form  can be submitted more than once</text-field>
    <button name="multi-submit-no-reset">Submit</button>
  </form>
</messageML>

Versions and Compatibility

Introduction to the enhanced tags

Symphony users can now tag financial instruments using the Enhanced Tag feature.

It displays a typeahead when the user presses # in a chat conversation. The upper section of the typeahead shows regular hashtags previously exchanged with that user and the lower section, under INSTRUMENTS shows Stocks, ADRs, ETFs and Indices.

By hovering over the Enhanced Tag, users can see essential reference data like company name, identifiers, exchange and currency.

The enhanced tags replace the existing $cashtags. This means that moving forward your apps and bots will need to handle enhanced tags instead of $cashtags.

Understanding the impact of the new tags

The impact of the enhanced tags on existing bots & apps has been carefully reviewed to ensure that there is no backward compatibility issue. However, we strongly recommend that you conduct some tests to validate the change.

Please read below to understand the changes introduced with the new enhanced tags.

Bots producing legacy $cashtags

• Existing bots can still produce legacy $cashtags both using the short tag notation (<tag cash="AAPL"/>), and using a Standard Entity ("type": "org.symphonyoss.fin.security")

• Existing bots can easily include enhanced tags in messageML now. To do so, you will need to cuse the <tag> and provide one or several identifiers for that instrument. The instrument will then be resolved against our reference database, and properly formatted in the message. More information is available here.

Bots consuming legacy $cashtags

• Bots consuming existing $cashtags in received messages are not impacted if they rely on the structured object (entityJSON). When they receive an enhanced tag, the exact same structure and properties will be present. There will be additional properties though, and the version field will be set to "2.0" instead of "1.0".

• Bots that rely on the text representation of the tags (message field instead of the entityJSON field) will also not be impacted. However, this is not a recommended practice as this text representation may change to match the enhanced tag displayed symbol instead of the existing ticker in the future (e.g., text would change from "$TSLA" to "TSLA US"). If you rely on the text representation of the $cashtag instead of the structured data, you should consider updating the bot to rely on the structured data included in the entityJSON instead.

• If you plan to upgrade your bot to leverage the new properties of the enhanced tags, please consider that you may still encounter legacy $cashtags for a long period of time, so should build around that. To detect if you are receiving a legacy tag or an enhanced one, you can rely on the version field included in the structure (org.symphonyoss.fin.security.version). It is set to "2.0" for the new enhanced tags.

Signals

• Existing signals will continue to work with the new enhanced tags. Messages containing the new tags will still match with the existing signals, meaning a signal matching "cash: AAPL" will match messages containing both "AAPL" and "AAPL US" for example.

• For now, it is not yet possible to create signals based on the newly introduced properties of the enhanced tags, but this will change in the coming months. For example, it is not yet possible to create a signal that will match only on "TSLA US", but if you create a signal that matches on "TSLA", it will match messages containing "TSLA US" as well.

• The Signal API has not changed. In the coming months the API may change to adapt to the new tags and in that case this change will be introduced following a notice period provided that there is an impact on the API contract.

Extension apps

• Existing apps that register a UI extension on $cashtag hovercards continue to receive the existing object for new enhanced tags.

• However, whenever your app is notified of a user click on the hovercard, the app will receive in addition to the existing object a new structure containing the new enhanced tags properties.

• If you decide to upgrade your app to leverage the new properties of the enhanced tags, please consider that you may still encounter legacy $cashtags for a long period of time, so should build around that. To detect if you are receiving a legacy tag or an enhanced one, you can rely on the version field included in the structure (org.symphonyoss.fin.security.version). It is set to "2.0" for the new enhanced tags.

Message format

Please note below the differences between the structures of the enhanced tags and the legacy $cashtags.

Structure of legacy $cashtags

Copy

// Presentation ML content of the message
<div data-format="PresentationML" data-version="2.0" class="wysiwyg">
  <p><span class="entity" data-entity-id="0">$SAN</span></p>
</div>

// Entities (entityJSON field in the message):
{
  "0": {
    "id": [
      {
        "type": "org.symphonyoss.fin.security.id.ticker",
        "value": "SAN"
      }
    ],
    "type": "org.symphonyoss.fin.security",
    "version": "1.0"
  }
}

Structure of enhanced tags

// Presentation ML content of the message
<div data-format="PresentationML" data-version="2.0" class="wysiwyg">
  <p><span class="entity" data-entity-id="0">$SAN</span></p>
</div>

// Entities (entityJSON field in the message):
{
  "0": {
    "id": [
      {
        "type": "org.symphonyoss.fin.security.id.ticker",
        "value": "SAN"
      },
      {
        "type": "org.symphonyoss.fin.security.id.uniqueId",
        "value": "91e3e37d-da68-42e8-ba05-94aa51aebb4e"
      },
      {
        "type": "org.symphonyoss.fin.security.id.fullBbgTicker",
        "value": "SAN FP Equity"
      },
      {
        "type": "org.symphonyoss.fin.security.id.isin",
        "value": "FR0000120578"
      },
      {
        "type": "org.symphonyoss.fin.security.id.figi",
        "value": "BBG000BWBBP2"
      },
      {
        "type": "org.symphonyoss.fin.security.id.localCode",
        "value": "SAN"
      },
      {
        "type": "org.symphonyoss.fin.security.id.operationalMic",
        "value": "XPAR"
      },
      {
        "type": "org.symphonyoss.fin.security.exchangeName",
        "value": "Euronext Paris"
      },
      {
        "type": "org.symphonyoss.fin.security.country",
        "value": "France"
      },
      {
        "type": "org.symphonyoss.fin.security.displayName",
        "value": "Sanofi"
      },
      {
        "type": "org.symphonyoss.fin.security.currency",
        "value": "EUR"
      },
      {
        "type": "org.symphonyoss.fin.security.instrumentTypeCode",
        "value": "EQS"
      },
      {
        "type": "org.symphonyoss.fin.security.instrumentTypeName",
        "value": "Equity Shares"
      },
      {
        "type": "org.symphonyoss.fin.security.rootBbgCompTicker",
        "value": "SAN"
      },
      {
        "type": "org.symphonyoss.fin.security.bbgcompticker",
        "value": "SAN FP"
      }
    ],
    "type": "org.symphonyoss.fin.security",
    "version": "2.0"
  }
} 

Tags

MessageML supports the following tags to embed additional information into messages: