Messages

Message API endpoints

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

• Message creation via the Create Message v4 endpoint

• Message creation in multiple conversations using the Blast Message endpoint

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

• Message suppression via the Suppress Message endpoint

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

Overview of the Message Flow

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

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

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

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

MessageML Render bot

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

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

Diagram of Symphony Messaging Message Flow:

The above diagram shows the following:

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

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

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

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

Message Identifiers:

Each message in Symphony Messaging has a unique message ID.

To find the message ID:

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

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

Encoding:

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

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

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

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

Message Size Limits

Messages may include:

• Maximum 80 entities (tags and mentions).

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

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

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

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

Message Delivery for External Rooms (Cross-Pod)

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

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