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.

Next Steps:

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!

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.

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:

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:

<messageML>
  <form id="form_id"><h4>Personal Information</h4>
    <text-field name="name_01" required="true" placeholder="Name"/>
    <text-field name="email_01" required="true" placeholder="email"/>

    <h4>Select your country</h4>
    <select name="country">
    <option value="opt1">Australia</option>
    <option value="opt2">Brazil</option>
    <option value="opt3">China</option>
    <option value="opt4">Denmark</option>
    <option value="opt5">Ecuador</option>
    <option value="opt6">France</option>
    <option value="opt7">Germany</option>
    <option value="opt8">Italy</option>
    <option value="opt9">Japan</option>
    </select>

    <h4>Choose your option</h4>            
    <radio name="example_radio" value="option_01" checked="true">Marked</radio>
    <radio name="example_radio" value="option_02">Unmarked</radio>

    <h4>Choose your option</h4>
    <checkbox name="checkbox_1" value="value01" checked="true">Checked</checkbox>
    <checkbox name="checkbox_2" value="value02">Unchecked</checkbox>

    <h4>Send a comment</h4>
    <textarea name="comment" placeholder="Add your comment here" required="true"></textarea>

    <button type="reset">Reset</button>
    <button name="submit_button" type="action">Submit</button>

  </form>
</messageML>

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:

{
    "id": "tkld79",
    "messageId": "iJXn_RBQwGmixJN94ZSfYn___oyx4HHubQ",
    "timestamp": 1594743557649,
    "type": "SYMPHONYELEMENTSACTION",
    "initiator": {
        "user": {
            "userId": 344147139494862,
            "firstName": "Reed",
            "lastName": "Feldman",
            "displayName": "Reed Feldman (SUP)",
            "email": "reed.feldman@symphony.com",
            "username": "reedUAT"
        }
    },
    "payload": {
        "symphonyElementsAction": {
            "stream": {
                "streamId": "IEj12WoWsfTkiqOBkATdUn___pFXhN9OdA",
                "streamType": "IM"
            },
            "formMessageId": "p1tZHt5dL8ZR5RPgl4TJ6X___oyx4sfxbQ",
            "formId": "form_id",
            "formValues": {
                "action": "submit_button",
                "name_01": "Reed Feldman",
                "email_01": "reed.feldman@symphony.com",
                "country": "opt1",
                "example_radio": "option_01",
                "checkbox_1": "value01",
                "comment": "My comment!"
            }
        }
    }
}

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:

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:

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

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:

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!

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

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

Generate your Bot

First, install yeoman and the Symphony Messaging Generator. Then, create a directory for your new bot project. Finally, launch the generator.

$ npm i -g yo @finos/generator-symphony
$ mkdir my-bot && cd $_
$ yo @finos/symphony

This will prompt you with a number of questions about your bot and pod configuration. Type in your bot's information, using arrow keys to scroll and press enter to move on to the next prompt.

When prompted for Select your type of application, choose Bot Application.

 __   __     ___                 _
 \ \ / /__  / __|_  _ _ __  _ __| |_  ___ _ _ _  _
  \ V / _ \ \__ \ || | '  \| '_ \ ' \/ _ \ ' \ || |
   |_|\___/ |___/\_, |_|_|_| .__/_||_\___/_||_\_, |
                 |__/      |_|                |__/

Welcome to Symphony Generator v2.7.1
Application files will be generated in folder: /home/user/code/my-bot
______________________________________________________________________________________________________
? Enter your pod host mycompany.symphony.com
? Enter your bot username my-bot
? Select your type of application Bot Application
? Select your programing language Java
? Select your framework Java (no framework)
? Select your build system Maven
? Enter your project groupId com.mycompany
? Enter your project artifactId bot-application
? Enter your base package com.mycompany.bot

Generating RSA keys...
   create rsa/publickey.pem
   create rsa/privatekey.pem
   create src/main/resources/config.yaml
   create src/main/resources/templates/gif.ftl
   create src/main/resources/templates/welcome.ftl
   create src/main/java/com/mycompany/bot/BotApplication.java
   create src/main/java/com/mycompany/bot/GifFormActivity.java
   create mvnw
   create mvnw.cmd
   create .mvn/wrapper/MavenWrapperDownloader.java
   create .mvn/wrapper/maven-wrapper.properties
   create pom.xml
   create .gitignore

[INFO] Scanning for projects...
[INFO]
[INFO] -------------------< com.mycompany:bot-application >--------------------
[INFO] Building bot-application 0.0.1-SNAPSHOT
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ bot-application ---
[INFO] Using 'UTF-8' encoding to copy filtered resources.
[INFO] Copying 3 resources
[INFO]
[INFO] --- maven-compiler-plugin:3.8.1:compile (default-compile) @ bot-application ---
[INFO] Changes detected - recompiling the module!
[INFO] Compiling 2 source files to /home/ys/code/hello/target/classes
[INFO]
[INFO] --- maven-resources-plugin:2.6:testResources (default-testResources) @ bot-application ---
[INFO] Using 'UTF-8' encoding to copy filtered resources.
[INFO] skip non existing resourceDirectory /home/ys/code/hello/src/test/resources
[INFO]
[INFO] --- maven-compiler-plugin:3.8.1:testCompile (default-testCompile) @ bot-application ---
[INFO] No sources to compile
[INFO]
[INFO] --- maven-surefire-plugin:2.12.4:test (default-test) @ bot-application ---
[INFO] No tests to run.
[INFO]
[INFO] --- maven-jar-plugin:2.4:jar (default-jar) @ bot-application ---
[INFO] Building jar: /home/ys/code/hello/target/bot-application-0.0.1-SNAPSHOT.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  1.473 s
[INFO] Finished at: 2023-07-05T15:40:04+08:00
[INFO] ------------------------------------------------------------------------

You can now update the service account my-bot with the following public key:

-----BEGIN RSA PUBLIC KEY-----
MIICCgKCAgEAvFZi2h0yX7uScduCRD+tCKOJAaMB3bNUyjXv/5f+aCMfzhfx9JpS
...
XCXnaO2GT22pmjjqLLUKzw2hump2fpAka2l8+mc0UzZc658JcROClEMCAwEAAQ==
-----END RSA PUBLIC KEY-----

Please submit these details to your pod administrator.
If you are a pod administrator, visit https://mycompany.symphony.com/admin-console

Your Java project has been successfully generated !

 __   __     ___                 _
 \ \ / /__  / __|_  _ _ __  _ __| |_  ___ _ _ _  _
  \ V / _ \ \__ \ || | '  \| '_ \ ' \/ _ \ ' \ || |
   |_|\___/ |___/\_, |_|_|_| .__/_||_\___/_||_\_, |
                 |__/      |_|                |__/

Welcome to Symphony Generator v2.7.1
Application files will be generated in folder: /home/user/code/my-bot
______________________________________________________________________________________________________
? Enter your pod host mycompany.symphony.com
? Enter your bot username my-bot
? Select your type of application Bot Application
? Select your programing language Python

Generating RSA keys...
   create rsa/publickey.pem
   create rsa/privatekey.pem
   create requirements.txt
   create resources/logging.conf
   create .gitignore
   create readme.md
   create resources/config.yaml
   create resources/gif.jinja2
   create src/__main__.py
   create src/activities.py
   create src/gif_activities.py

No change to package.json was detected. No package manager install will be executed.

You can now update the service account my-bot with the following public key:

-----BEGIN RSA PUBLIC KEY-----
MIICCgKCAgEA059e0WKgmDVyazFxszs0Xty17iLemhyIrghwfn9XGEwvK40q/dE0
...
ST7yvzUeAy5Xkhad6ySvSviK9dt2Zl+FLVu3uwg1bMfMzXN2T44afp0CAwEAAQ==
-----END RSA PUBLIC KEY-----

Please submit these details to your pod administrator.
If you are a pod administrator, visit https://mycompany.symphony.com/admin-console

Your Python project has been successfully generated !
Install environment: python3 -m venv env
Activate virtual environment: source env/bin/activate
Install all required packages with: pip3 install -r requirements.txt
And run your bot with: python3 -m src

Configuration

The Symphony Messaging Generator creates a basic configuration file that works for fully cloud-hosted pods. If you have additional network requirements like a web proxy or an on-premise Key Manager and API Agent, refer to the complete configuration guide below for more details.

Create Service Account

For any bot to work, it requires a service account with a matching username and public key. The Symphony Messaging Generator creates a configuration file based on the answers supplied, including the bot username and the path to the generated key pair. These can be changed by modifying the config.yaml file. If you do not already have a service account set up, follow the instructions on this page to continue.

Test your Bot

Open the project in your preferred IDE and use the IDE's launch/debug feature to start the bot. Alternatively, continue using the command-line to launch the bot using the appropriate command.

# Maven + No Framework
# Edit package and main class if changed
./mvnw exec:java -Dexec.mainClass=com.mycompany.bot.BotApplication

# Maven + Spring
./mvnw spring-boot:run

# Gradle + No Framework
./gradlew run

# Gradle + Spring
./gradlew bootRun

# For the first run, create a virtual environment and install requirements
python3 -m venv env
pip3 install -r requirements.txt

# For subsequent runs, 
source env/bin/activate  # macOS or Linux
env\Scripts\activate.bat # Windows

# Run the bot
python3 -m src

The bot should start up successfully and the following log indicates that it is up and listening:

Build your Bot

Now that you have a basic bot project ready, you can proceed to find out more about building bots using the respective kits:

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?

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:

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:

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

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:

Overview

In an enterprise environment, it is very common to have an internal root certificate authority (root CA) that signs all certificates used internally for TLS termination on HTTPS sites. While this trust is federated on the operating system level for all domain-connected Windows workstations, non-Windows servers are typically not configured the same way. Even on a Windows workstation, your Java runtime might not necessarily trust the enterprise root CA certificates.

If a Java application attempts to make a connection to an untrusted remote server, it will throw an SSLException and fail to connect.

Java Truststores

A Java truststore is a bundle of certificates used when establishing connections to remote servers (this could be internal or on the Internet). Each Java runtime ships with a default truststore called cacerts. Adding certificates directly into cacerts is usually not recommended unless there is a centrally-managed deployment process for all workstations and servers.

Bot Truststore

A bot requires connections to several servers like the key manager or API agent, as defined in your bot configuration. This configuration should also define the path to a custom truststore, which ensures that the trust relationship is maintained even as the bot's deployment location is moved, as long as the truststore file is moved together with the deployment artifacts.

BDK for Java

The BDK for Java uses the JKS format and the configuration is under the ssl section within the config.yaml:

If you are using the BDK for Java's Spring Starters, modify the appropriate application.yaml file to include the ssl section under the bdk section:

BDK for Python

The BDK for Python uses a concatenated PKCS format. Your config.yaml should look like this:

Certificate Chains

A typical internal certificate has has least 2 certificates in its chain - the certificate itself as well as the root CA certificate that signed it. Some enterprises will have intermediate CAs to form a 3-certificate chain. When Java establishes a connection to a remote server, it requires all signing certificates in that chain to be trusted. Hence, when building a truststore, you will need to import every signing certificate in the chain of each remote server that is not already present in the cacerts bundle.

Publicly-trusted signing certificates from established certificate authorities are already in cacerts so you will most likely not need to import certificates for services on the public Internet. However, if the Java runtime you are using pre-dates the existence of those certificates, then you will need to add them manually.

Building a Java Truststore

The keytool command that ships with all Java runtimes is used to manage truststores. You can build a new truststore or append to an existing one using the same command as follows:

Automatic: Convenience Shell Script

You may use the following convenience shell script to automatically build out a new truststore based on a list of servers. Please remember to include all possible connections that your bot requires. This may include: all Key Manager servers, all API Agent servers, the Symphony Messaging pod, any other third-party or internal endpoints that the bot will interact with.

Manual: Collating Certificates in Windows

If you have no access to a Linux-based shell, you can also manually perform this process within a Windows environment. All you need is a browser and a Java runtime with keytool installed.

Step 1: Visit an endpoint on each server in your browser and view the certificate

Step 2: Select the next signing certificate

In the Certification Path tab, select the end certificate's parent and View Certificate

Step 3: Export the certificate

In the Details tab, click Copy to File.. and select the Base-64 encoded X.509 option then save the certificate to disk.

Step 4: Repeat for the rest of the chain

Repeat Steps 2 and 3 until you have exported all signing certificates in the chain.

Step 5: Build the trust store

Launch command prompt and repeat this command for each exported certificate

You can verify the entries by using the -list option:

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:

{
    "id": "9rc1dr",
    "messageId": "Fd4Pc8xO5Vg6hVfzabFe2X___oyM1eXobQ",
    "timestamp": 1595365005847,
    "type": "MESSAGESENT",
    "initiator": {
        "user": {
            "userId": 344147139494862,
            "firstName": "Reed",
            "lastName": "Feldman",
            "displayName": "Reed Feldman (SUP)",
            "email": "reed.feldman@symphony.com",
            "username": "reedUAT"
        }
    },
    "payload": {
        "messageSent": {
            "message": {
                "messageId": "Fd4Pc8xO5Vg6hVfzabFe2X___oyM1eXobQ",
                "timestamp": 1595365005847,
                "message": "<div data-format=\"PresentationML\" data-version=\"2.0\" class=\"wysiwyg\"><p>hi</p></div>",
                "data": "{}",
                "user": {
                    "userId": 344147139494862,
                    "firstName": "Reed",
                    "lastName": "Feldman",
                    "displayName": "Reed Feldman (SUP)",
                    "email": "reed.feldman@symphony.com",
                    "username": "reedUAT"
                },
                "stream": {
                    "streamId": "IEj12WoWsfTkiqOBkATdUn___pFXhN9OdA",
                    "streamType": "IM"
                },
                "externalRecipients": false,
                "userAgent": "DESKTOP-43.0.0-10902-MacOSX-10.14.6-Chrome-83.0.4103.61",
                "originalFormat": "com.symphony.messageml.v2",
                "sid": "98202eac-dcf4-4b1e-a120-596db38319dc"
            }
        }
    }
}

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:

public class Example {

    public static void main(String[] args) { 
        // create bdk entry point
        final SymphonyBdk bdk = new SymphonyBdk(loadFromClasspath("/config.yaml"));
        
        // create listener to be subscribed
        final RealTimeEventListener listener = new RealTimeEventListener() {
            @Override
            public void onMessageSent(V4Initiator initiator, V4MessageSent event) {
                log.info("Message sent");
            }
        };

        // subscribe a listener
        bdk.datafeed().subscribe(listener);
       
        // start reading the datafeed 
        bdk.datafeed().start(); 
    }
}

from symphony.bdk.core.config.loader import BdkConfigLoader
from symphony.bdk.core.symphony_bdk import SymphonyBdk
from symphony.bdk.core.service.datafeed.real_time_event_listener import RealTimeEventListener

class RealTimeEventListenerImpl(RealTimeEventListener):

    async def on_message_sent(self, initiator, event):
        # message received, interact with it
        pass

async def run():
    async with SymphonyBdk(BdkConfigLoader.load_from_symphony_dir("config.yaml")) as bdk:
        datafeed_loop = bdk.datafeed()
        # subscribe your listener
        datafeed_loop.subscribe(RealTimeEventListenerImpl())
        # start reading the datafeed
        await datafeed_loop.start()

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

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

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.

$ openssl genrsa -aes256 -passout pass:$PASSWORD -out admin-key.pem 4096
$ openssl req -new -key admin-key.pem -passin pass:$PASSWORD -subj "/CN=$USERNAME/O=Symphony Communications LLC/OU=NOT FOR PRODUCTION USE/C=US" -out admin-req.pem
$ openssl x509 -req -sha256 -days 2922 -in admin-req.pem -CA $CA_CERT -CAkey $CA_KEY -passin pass:$CA_PASSWORD -out admin-cert.pem -set_serial 0x1
$ openssl pkcs12 -export -out admin.p12 -aes256 -in admin-cert.pem -inkey admin-key.pem -passin pass:$PASSWORD -passout pass:$OUTPUT_PASSWORD

• 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

$ curl --cert bot.user1.p12:mypassword
https://${symphony.url}/sessionauth/v1/authenticate
-X POST

A successful response:

{
  "name":"sessionToken",  
  "token":"SESSION_TOKEN"
}

$ curl --cert bot.user1.p12:mypassword
https://${symphony.url}/keyauth/v1/authenticate
-X POST

A successful response:

{
  "name":"keyManagerToken",
  "token":"KEY_MANAGER_TOKEN"
}

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

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:

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

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

• 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:

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

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

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:

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

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

Summary

The Authentication process requires the following steps:

1. The user creates a public/private RSA key pair.

2. The admin imports the public key into the pod using the Admin Console or public APIs.

3. The user creates a short-lived JWT (JSON Web Token) and signs it with their private key.

4. The bot makes a call the the authentication endpoints. Here, the server checks the signature of the JWT against the public key and returns an authentication token.

1. Create an RSA Key Pair

The public/private key pair for signing authentication requests requires the following:

• A X.509 format for public keys and PKCS#1 or PKCS#8 for private keys

• PEM-encoded keys

Generate the PKCS#1 keys manually using the following commands:

$ openssl genrsa -out mykey.pem 4096
$ openssl rsa -in mykey.pem -pubout -out pubkey.pem

Generate the PKCS#8 keys manually using the following commands. You can provide the Service Account's username as the Common Name (CN) but it is not a mandatory requirement.

$ openssl genrsa -out privatekey.pem 4096
$ openssl req -newkey rsa:4096 -x509 -key privatekey.pem -out publickey.cer
$ openssl pkcs8 -topk8 -nocrypt -in privatekey.pem -out privatekey.pkcs8
$ openssl x509 -pubkey -noout -in publickey.cer > publickey.pem

Sign the authentication request using either privatekey.pkcs8 or privatekey.pem, depending on the support available in the JWT library.

The file publickey.pem is the public key. This is the key you will import into the pod in step 2.

2. Import Public Key into the Pod

Navigate to the Admin Console and create a new Service Account. Copy the contents of the pubkey.pem file you just created and paste into the textbox under the Authentication section:

Add your bot's basic information:

If successful, you should see the following:

3. Generate a signed JWT Token

To authenticate on the Pod and the Key Manager, the bot must call the authentication endpoints, passing a short-lived JWT token in the body of the request. The JWT token must contain the following:

• a subject matching the username of the user to authenticate

• an expiration time of no more than 5 minutes from the current timestamp (needed to prevent replay attacks)

• a signature by a private RSA key matching a public key stored for the user in the Pod

The following script generates the authentication request:

package com.symphony.util.jwt;

import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;
import org.bouncycastle.asn1.pkcs.RSAPrivateKey;
import org.bouncycastle.crypto.params.RSAPrivateCrtKeyParameters;
import org.bouncycastle.crypto.util.PrivateKeyInfoFactory;
import org.bouncycastle.openssl.jcajce.JcaPEMKeyConverter;
import org.bouncycastle.util.io.pem.PemObject;
import org.bouncycastle.util.io.pem.PemReader;

import java.io.FileNotFoundException;
import java.io.IOException;
import java.io.StringReader;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.security.GeneralSecurityException;
import java.security.Key;
import java.security.KeyFactory;
import java.security.PrivateKey;
import java.security.spec.PKCS8EncodedKeySpec;
import java.util.Base64;
import java.util.Date;
import java.util.stream.Stream;


/**
 * Class used to generate JWT tokens signed by a specified private RSA key.
 * Libraries needed as dependencies:
 *  - BouncyCastle (org.bouncycastle.bcpkix-jdk15on) version 1.59.
 *  - JJWT (io.jsonwebtoken.jjwt) version 0.9.1.
 * 
 * 
 */
public class JwtHelper {

  // PKCS#8 format
  private static final String PEM_PRIVATE_START = "-----BEGIN PRIVATE KEY-----";
  private static final String PEM_PRIVATE_END = "-----END PRIVATE KEY-----";

  // PKCS#1 format
  private static final String PEM_RSA_PRIVATE_START = "-----BEGIN RSA PRIVATE KEY-----";
  private static final String PEM_RSA_PRIVATE_END = "-----END RSA PRIVATE KEY-----";


  /**
   * Get file as string without spaces
   * @param filePath: filepath for the desired file.
   * @return
   */
  public static String getFileAsString(String filePath) throws IOException {
    StringBuilder message = new StringBuilder();
    String newline = System.getProperty("line.separator");

    if (!Files.exists(Paths.get(filePath))) {
      throw new FileNotFoundException("File " + filePath + " was not found.");
    }

    try (Stream<String> stream = Files.lines(Paths.get(filePath))) {

      stream.forEach(line -> message
          .append(line)
          .append(newline));

      // Remove last new line.
      message.deleteCharAt(message.length() -1);
    } catch (IOException e) {
      System.out.println(String.format("Could not load content from file: %s due to %s",filePath, e));
      System.exit(1);
    }

    return message.toString();
  }

  /**
   * Creates a JWT with the provided user name and expiration date, signed with the provided private key.
   * @param user the username to authenticate; will be verified by the pod
   * @param expiration of the authentication request in milliseconds; cannot be longer than the value defined on the pod
   * @param privateKey the private RSA key to be used to sign the authentication request; will be checked on the pod against
   * the public key stored for the user
   */
  private static String createSignedJwt(String user, long expiration, Key privateKey) {

    return Jwts.builder()
        .setSubject(user)
        .setExpiration(new Date(System.currentTimeMillis() + expiration))
        .signWith(SignatureAlgorithm.RS512, privateKey)
        .compact();
  }

  /**
   * Create a RSA Private Key from a PEM String. It supports PKCS#1 and PKCS#8 string formats
   */
  private static PrivateKey parseRSAPrivateKey(String privateKeyFilePath) throws GeneralSecurityException, IOException {
    String pemPrivateKey = getFileAsString(privateKeyFilePath);
    try {

      if (pemPrivateKey.contains(PEM_PRIVATE_START)) {              // PKCS#8 format

        String privateKeyString = pemPrivateKey
            .replace(PEM_PRIVATE_START, "")
            .replace(PEM_PRIVATE_END, "")
            .replace("\\n", "\n")
            .replaceAll("\\s", "");
        byte[] keyBytes = Base64.getDecoder().decode(privateKeyString.getBytes(StandardCharsets.UTF_8));
        PKCS8EncodedKeySpec keySpec = new PKCS8EncodedKeySpec(keyBytes);
        KeyFactory fact = KeyFactory.getInstance("RSA");
        return fact.generatePrivate(keySpec);

      } else if (pemPrivateKey.contains(PEM_RSA_PRIVATE_START)) {   // PKCS#1 format

        try (PemReader pemReader = new PemReader(new StringReader(pemPrivateKey))) {
          PemObject privateKeyObject = pemReader.readPemObject();
          RSAPrivateKey rsa = RSAPrivateKey.getInstance(privateKeyObject.getContent());
          RSAPrivateCrtKeyParameters privateKeyParameter = new RSAPrivateCrtKeyParameters(
              rsa.getModulus(),
              rsa.getPublicExponent(),
              rsa.getPrivateExponent(),
              rsa.getPrime1(),
              rsa.getPrime2(),
              rsa.getExponent1(),
              rsa.getExponent2(),
              rsa.getCoefficient()
          );

          return new JcaPEMKeyConverter().getPrivateKey(PrivateKeyInfoFactory.createPrivateKeyInfo(privateKeyParameter));
        } catch (IOException e) {
          throw new GeneralSecurityException("Invalid private key.");
        }

      } else {
        throw new GeneralSecurityException("Invalid private key.");
      }
    } catch (Exception e) {
      throw new GeneralSecurityException(e);
    }
  }

  public static String createJwt(String username, String privateKeyFilePath) throws IOException, GeneralSecurityException {
    final long expiration = 300000L;
    final PrivateKey privateKey = parseRSAPrivateKey(privateKeyFilePath);
    return createSignedJwt(username, expiration, privateKey);
  }

  public static void main(String[] args) throws IOException, GeneralSecurityException {
    final String username = System.getProperty("user");
    final String privateKeyFile = System.getProperty("key");

    final String jwt = createJwt(username, privateKeyFile);
    System.out.println(jwt);
  }
}

"""
0) Use python 3

1) Install python dependency required to run this script by:
    pip install python-jose

2) The .pem file used in this script was generated from the previous step of this tutorial.

3) Create a create_jwt.py file, copy and paste the content you see here. Place your private key .pem file in the same directory as this script.

4) Change the value of \'sub\' to your Symphony service account username. Change the filename of the .pem file to the filename of your .pem file.

5) Generate jwt token simply by:
    python create_jwt.py

6) You will see the jwt token in terminal output.
"""

from jose import jwt
import datetime as dt


def create_jwt():
    private_key = get_key()
    expiration_date = int(dt.datetime.now(dt.timezone.utc).timestamp() + (5 * 58))
    payload = {
        'sub': "username_of_service_account",
        'exp': expiration_date
    }
    encoded = jwt.encode(payload, private_key, algorithm='RS512')
    print(encoded)


def get_key():
    with open('filename_of_private_key.pem', 'r') as f:
        content =f.readlines()
        key = ''.join(content)
        return key


if __name__ == '__main__':
    create_jwt()

// Based on https://github.com/jwtk/njwt
'use strict';

let crypto = require('crypto');

function nowEpochSeconds() {
    return Math.floor(new Date().getTime() / 1000);
}

function base64urlEncode(str) {
    return new Buffer(str)
        .toString('base64')
        .replace(/\+/g, '-')
        .replace(/\//g, '_')
        .replace(/=/g, '');
}

function Jwt(username, signingKey) {

    this.header = {};
    this.body = {};
    this.header.alg = 'RS512';
    this.body.sub = username
    this.body.exp = (nowEpochSeconds() + (5 * 60)); // five minutes in seconds
    this.signingKey = signingKey;

    return this;
}

Jwt.prototype.sign = function sign(payload, cryptoInput) {
    let buffer = crypto.createSign('RSA-SHA512').update(payload).sign(cryptoInput);

    return base64urlEncode(buffer);
};

Jwt.prototype.compact = function compact() {

    let segments = [];
    segments.push(base64urlEncode(JSON.stringify(this.header)));
    segments.push(base64urlEncode(JSON.stringify(this.body)));
console.log("segments ", segments);
console.log("segments join ", segments.join('.'));
console.log("Signing key ", this.signingKey);
    this.signature = this.sign(segments.join('.'), this.signingKey);
    segments.push(this.signature);

    return segments.join('.');
};

const secret = "-----BEGIN RSA PRIVATE KEY-----\n" +
"...REDACTED..."
"-----END RSA PRIVATE KEY-----";

const user = 'bot.user1';
const jwt = new Jwt(user, secret);
const jws = jwt.compact();

console.log("========== JWS ==========")
console.log(jws);

using Microsoft.IdentityModel.Tokens;
using Org.BouncyCastle.Crypto;
using Org.BouncyCastle.Crypto.Parameters;
using Org.BouncyCastle.OpenSsl;
using System;
using System.Configuration;
using System.IdentityModel.Tokens.Jwt;
using System.IO;
using System.Security;
using System.Security.Claims;
using System.Security.Cryptography;

namespace Symphony.Util.Jwt
{
    /// <summary>
    /// Class used to generate JWT tokens signed by a specified private RSA key.
    /// Libraries needed as dependencies:
    ///     - BouncyCastle version >= 1.8.5
    ///     - System.IdentityModel.Tokens.Jwt version >= 5.4.0
    /// </summary>
    public class JwtHelper
    {
        /// <summary>
        /// Creates a JWT with the provided user name and expiration date, signed with the provided private key.
        /// </summary>
        /// <param name="user">The username to authenticate; will be verified by the pod.</param>
        /// <param name="expiration">Expiration of the authentication request in milliseconds; cannot be longer than the value defined on the pod.</param>
        /// <param name="privateKey">The private RSA key to be used to sign the authentication request; will be checked on the pod against the public key stored for the user.</param>
        public static string CreateSignedJwt(string user, double expiration, SecurityKey privateKey)
        {
            var handler = new JwtSecurityTokenHandler
            {
                SetDefaultTimesOnTokenCreation = false
            };

            var tokenDescriptor = new SecurityTokenDescriptor
            {
                Expires = DateTime.Now.AddMilliseconds(expiration),
                Subject = new ClaimsIdentity(new[] {
                    new Claim("sub", user)
                }),

                SigningCredentials = new SigningCredentials(privateKey, SecurityAlgorithms.RsaSha512, SecurityAlgorithms.Sha512Digest)
            };
            SecurityToken token = handler.CreateToken(tokenDescriptor);
            return handler.WriteToken(token);
        }

        /// <summary>
        /// Create a RSA Private Key from a PEM String. It supports PKCS#1 and PKCS#8 string formats.
        /// </summary>
        public static SecurityKey ParseRSAPrivateKey(String privateKeyFilePath)
        {
            if (!File.Exists(privateKeyFilePath))
            {
                throw new FileNotFoundException($"File {privateKeyFilePath} was not found");
            }

            var cryptoServiceProvider = new RSACryptoServiceProvider();
            using (var privateKeyTextReader = new StringReader(File.ReadAllText(privateKeyFilePath)))
            {
                object rsaKey = null;
                try
                {
                    rsaKey = new PemReader(privateKeyTextReader).ReadObject();
                }
                catch (Exception)
                {
                    throw new SecurityException("Invalid private key.");
                }


                RsaPrivateCrtKeyParameters privateKeyParams = null;
                // PKCS#8 format.
                if (rsaKey is RsaPrivateCrtKeyParameters)
                {
                    privateKeyParams = (RsaPrivateCrtKeyParameters)rsaKey;
                }
                // PKCS#1 format
                else if (rsaKey is AsymmetricCipherKeyPair)
                {
                    AsymmetricCipherKeyPair readKeyPair = rsaKey as AsymmetricCipherKeyPair;
                    privateKeyParams = ((RsaPrivateCrtKeyParameters)readKeyPair.Private);
                }
                else
                {
                    throw new SecurityException("Invalid private key.");
                }

                var parms = new RSAParameters
                {
                    Modulus = privateKeyParams.Modulus.ToByteArrayUnsigned(),
                    P = privateKeyParams.P.ToByteArrayUnsigned(),
                    Q = privateKeyParams.Q.ToByteArrayUnsigned(),
                    DP = privateKeyParams.DP.ToByteArrayUnsigned(),
                    DQ = privateKeyParams.DQ.ToByteArrayUnsigned(),
                    InverseQ = privateKeyParams.QInv.ToByteArrayUnsigned(),
                    D = privateKeyParams.Exponent.ToByteArrayUnsigned(),
                    Exponent = privateKeyParams.PublicExponent.ToByteArrayUnsigned()
                };

                cryptoServiceProvider.ImportParameters(parms);
            }

            return new RsaSecurityKey(cryptoServiceProvider.ExportParameters(true));
        }

        public static string CreateJwt(string username, string privateKeyFilePath)
        {
            double expiration = 300000; // 5 minutes = 5*60*1000
            SecurityKey privateKey = ParseRSAPrivateKey(privateKeyFilePath);
            return CreateSignedJwt(username, expiration, privateKey);
        }

        static void Main(string[] args)
        {
            string username = ConfigurationManager.AppSettings.Get("user");
            string privateKeyFile = ConfigurationManager.AppSettings.Get("key");

            string jwt = CreateJwt(username, privateKeyFile);
            Console.WriteLine(jwt);
            Console.WriteLine("Press enter to exit...");
            Console.ReadLine();
        }
    }
}

The output of the script is a JWT:

eyJhbGciOiJSUzUxMiJ9.eyJzdWIiOiJib3QudXNlcjEiLCJleHAiOjMwNDMwOTY0ODV9.X9vZReZigFtJ8NDsaJ9viUp2jtc-_ktVFLm17ubEzmSJbHXS_LNy5nL6E6R8GY71g8Vuonb8qSIwy8zoR_TcUvuPAQLxCAlvQn96jFnjg4aFO3kWkFMLFgwJWWR4hn2UocdTS_pu7ROafn6rjvLJdKGEWDOHKw6JX2_Qj3uzU3LeAFhUVU8Tmop3A2OTVUkPlWJwJimIas66kFgq61uGps8RT9YMs74bxGvOJvInidK2N_dqJMDPgb4ySOBHewlhe1ziUWM-21HDq1RvmadTWoPRKRXdt4oPRoxr4KRgmluaQpz8njL7Em9Sh1bCKJWuIjlXQPOcF3SFibbAcLwr40UnT2sM2LMJtkj0BHIU_5Ans0fN1x8hKtfWX_ArzLJTCBCCqswmq8Q3vxo0-SHe33Idy99TfkrY-C8G-fgPFvs9L7695MOcYAq8SpbZQlX-anpcqLQfsw6V-V0ZEAUeSHpnZrHvwmQjEmU9wXWzvAgCpF9kEt_I4Hpu8DTx2VzVj7CRU1Lu5NPHoESjI6VKJWcCH68TvkBB88jJqflXcQfbLUdK1sjDwDKl3BurmGBZSlD0ymuBXaQe4yol4zxXzSuWo6VCy5ykXee0mZm5t9-9wJujcjnGyKjNNSVLhajrmo6BRDN86I_xgV33SHgdrJKyQCO8LzUK4ArEMYlEY0I

4. Authenticate

Obtain a valid Session Token by making a POST request to your company's Session Auth endpoint:

$ curl -d '{"token":"eyJhbGciOiJSUzUxMiJ9...ik0iV6K9FrEhTAf71cFs"}' https://${symphony.url}:443/login/pubkey/authenticate

A successful response:

{"token":"eyJhbGciOiJSUzUxMiJ9...7oqG1Kd28l1FpQ","name":"sessionToken"}

Obtain a valid Key Manager Token by making a POST request to your company's Key Manager Auth endpoint:

$ curl -d '{"token":"eyJhbGciOiJSUzUxMiJ9...ik0iV6K9FrEhTAf71cFs"}' https://${symphony.url}:443/relay/pubkey/authenticate

A successful response:

{"token":"0100e4fe...REDACTED...f729d1866f","name":"keyManagerToken"}

Replace/Revoke Key

You can replace the public key pubkeyA for a user with a new key, pubkeyB (for example, as part of an organization's key rotation schedule). Note the following outcomes:

• When a key is replaced, the key pubkeyA becomes the user's previous key, and the newly uploaded pubkeyB becomes the current key.

• The previous key is valid for 72 hours, but you can extend that period indefinitely in intervals of 72 hours.

• While the previous key is valid, both keys can be used for authentication. When it expires, it can no longer be used to authenticate the user.

• A user can have at most one previous key.

Alternatively, you can revoke a user key (current or previous), for example, if the key is compromised. Note the following outcomes:

• When a key is revoked, it can no longer be used for authentication.

• If a user has a non-expired previous key and their current key is revoked, the previous key becomes the new current key.

• When a key is revoked, the user's sessions initiated with RSA authentication are invalidated.

To replace/revoke a key, navigate to the Bot's account in the admin portal > RSA > Replace or Revoke:

You can also use the following REST API call to programmatically replace a public key:

curl -H 'sessionToken: eyJhbGciOiJSUzUxMiJ9...O3iq8OEkcnvvMFKg' -d '{

  {
    "currentKey": {
      "key": "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhki...WMCAwEAAQ==\n-----END PUBLIC KEY-----",
      "action": "SAVE"
    }
  }
}' https://${symphony.url}:443/pod/v2/admin/user/68719476742/update

{
  "userAttributes": {
    "emailAddress": "demo-bot1@symphony.com",
    "userName": "demo-bot1",
    "displayName": "DemoBot1",
    "companyName": "pod1",
    "accountType": "SYSTEM",
    "currentKey": {
      "key": "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhk...ghUGWMCAwEAAQ==\n-----END PUBLIC KEY-----"
    },
    "previousKey": {
      "key": "-----BEGIN PUBLIC KEY-----MIICIjANBgkqhki...hUGWMCAwEAAQ==-----END PUBLIC KEY-----",
      "expirationDate": 1522675669714
    }
  },
  "userSystemInfo": {
    "id": 68719476742,
    "status": "ENABLED",
    "createdDate": 1522318499000,
    "createdBy": "68719476737",
    "lastUpdatedDate": 1522416469717,
    "lastLoginDate": 1522416465367
  },
  "roles": [
    "INDIVIDUAL"
  ]
}

Additionally you can programmatically revoke a public key using either currentKey or previousKey. Use the following REST request to programmatically revoke a public key using currentKey:

curl -H 'sessionToken: eyJhbGciOiJSUzUxMiJ9...O3iq8OEkcnvvMFKg' -d '{
  {
    "currentKey": {"action":"REVOKE"}
  }
}' https://localhost.symphony.com:443/pod/v2/admin/user/68719476742/update

{
  "userAttributes": {
    "emailAddress": "bot.user1@localhost.symphony.com",
    "userName": "bot.user1",
    "displayName": "Local Bot01",
    "companyName": "pod1",
    "accountType": "SYSTEM"
  },
  "userSystemInfo": {
    "id": 68719476742,
    "status": "ENABLED",
    "createdDate": 1522318499000,
    "createdBy": "68719476737",
    "lastUpdatedDate": 1522416469717,
    "lastLoginDate": 1522416465367
  },
  "roles": [
    "INDIVIDUAL"
  ]
}

Use the following REST request to programmatically revoke a public key using previousKey:

curl -H 'sessionToken: eyJhbGciOiJSUzUxMiJ9...O3iq8OEkcnvvMFKg' -d '{
  {
    "previousKey": {"action":"REVOKE"} 
  }
}' https://localhost.symphony.com:443/pod/v2/admin/user/68719476742/update

{
  "userAttributes": {
    "emailAddress": "demo-bot1@symphony.com",
    "userName": "demo-bot1",
    "displayName": "DemoBot1",
    "companyName": "pod1",
    "accountType": "SYSTEM",
    "currentKey": {
      "key": "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhk...ghUGWMCAwEAAQ==\n-----END PUBLIC KEY-----"
    }
  },
  "userSystemInfo": {
    "id": 68719476742,
    "status": "ENABLED",
    "createdDate": 1522318499000,
    "createdBy": "68719476737",
    "lastUpdatedDate": 1522416469717,
    "lastLoginDate": 1522416465367
  },
  "roles": [
    "INDIVIDUAL"
  ]
}

Extending a Public Key

Use the following REST request to programmatically extend a public key:

curl -H 'sessionToken: eyJhbGciOiJSUzUxMiJ9...O3iq8OEkcnvvMFKg' -d '{
  {
    "previousKey": { "action": "EXTEND" } 
  }
}' https://localhost.symphony.com:443/pod/v2/admin/user/68719476742/update

{
  "userAttributes": {
    "emailAddress": "demo-bot1symphony.com",
    "userName": "demo-bot1",
    "displayName": "DemoBot1",
    "companyName": "pod1",
    "accountType": "SYSTEM",
    "currentKey": {
      "key": "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhk...ghUGWMCAwEAAQ==\n-----END PUBLIC KEY-----"
    },
    "previousKey": {
      "key": "-----BEGIN PUBLIC KEY-----MIICIjANBgkqhki...hUGWMCAwEAAQ==-----END PUBLIC KEY-----",
      "expirationDate": 1522675669714
    }
  },
  "userSystemInfo": {
    "id": 68719476742,
    "status": "ENABLED",
    "createdDate": 1522318499000,
    "createdBy": "68719476737",
    "lastUpdatedDate": 1522416469717,
    "lastLoginDate": 1522416465367
  },
  "roles": [
    "INDIVIDUAL"
  ]
}

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

Message API endpoints

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

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:

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

Diagram of Symphony Messaging Message Flow:

The above diagram shows the following:

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

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 Delivery for External Rooms (Cross-Pod)

Tags

The Apache Freemarker uses the HTML output format by default. In some cases, special characters placed within the MessageML must be HTML-escaped, otherwise, the request sending the MessageML will receive a 400 error response. The following are examples of valid HTML-escaping:

Examples

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

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

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.

Attributes supported in messageML tags

Tags support the following style attributes where applicable:

Go further...

To learn more about Symphony's built in styles, continue here:

Tags

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

Examples

Here after you can find an example of a message sent by a bot and containing these tags specific to Symphony Messaging as well as the structure of the messageML sent:

Mentions

Free-text Tags

Enhanced tags (Financial instruments)

Below several examples of financial instruments, using different types of identifiers and filters.

When identifiers and filters are not sufficient to identify a unique match, or when an instrument is not found in our reference database, an error is returned, except if a fallback-ticker is specified.

Chime