Messages
Bots in Symphony can use the following API endpoints to create, update and suppress messages in Symphony chats:
Please see below a quick animation showing a simple lifecycle of a bot message in Symphony with a message created by the bot, updated three times, and then finally suppressed.
In the Symphony 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.
Note: MessageML is just a subset of PresentationML that makes it easier to construct messages from your bot. The API can ingest either MessageML or PresentationML. However, the API will only deliver messages as PresentationML to a bot.
The MessageML Render bot is a productivity tool that helps developers to create chat messages compliant with Symphony’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. If this link doesn't work, you can look for MessageML Render bot in the directory.
The Render bot is currently in Beta. Your feedback is welcome.
The above diagram shows the following:
- 1.
- 2.The Agent API encrypts the messages, and converts them to PresentationML where they are stored in Symphony's data store.
- 3.The Symphony 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.
Each message in Symphony has a unique message ID.
To find the message ID:
- In the Symphony 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
messageIDis 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.
StreamID | URL Safe Base64 encoded StreamID |
RUkxW4x40aB74g0UWpaMw3///ozLPsapdA== | RUkxW4x40aB74g0UWpaMw3___ozLPsapdA |
Messages may include:
- Maximum 40 entities (#hashtags, $cashtags, 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)
Example of payload if the message exceeds the total size limit (default being 1.5Mb)
{
message=Limit message-content-max-total-size reached,
status=PAYLOAD_TOO_LARGE,
code=LIMIT_MESSAGE_CONTENT_MAX_TOTAL_SIZE_REACHED
}
In the Symphony 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.
Last modified 14d ago