Overview of Messages

This article gives an overview of the Symphony message workflow and shows how message representations are used throughout the workflow.

Overview of the Message Workflow

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

  • MessageML v2: 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.

Diagram of the Symphony Message Workflow

The following diagram represents an overview of the message workflow, described in detail below.

The diagram shows the following:

  1. Your bot uses the agent API to send messages in MessageML.
  2. The agent compiles the messages and stores them in Symphony's data store in PresentationML.
  3. The agent's Data Feed outputs messages in PresentationML.
  4. A web client consumes messages in the PresentationML format from the data store and uses a renderer to display them in an ExtensionML specific to the requirements of the web client. If a web client is not installed, the presentation defaults to PresentationML.
  5. Services output messages in various types of markup. The Dialog service generates ExtensionML, which allows interactivity. Since a share is placed into a message, the Share service generates a message in PresentationML along with its corresponding entity JSON. The share service also generates the equivalent markdown for use by older clients.

The Main Entities of the Workflow

The main entities in the workflow are:

  • bot: An entity built on the Symphony API, such as a chat application that sends messages using the API. Messages are sent in MessageML.
  • agent: The Symphony process that encrypts and decrypts message payloads sent and received by an API caller. An agent includes a data feed from which messages can be read. The agent and its data feed output messages in PresentationML.
  • data store: The underlying database that stores messages in MessageML.
  • web client: A Symphony application that is embedded within the Symphony user interface. A web client can use services and a renderer (see next).
  • renderer: An object that takes a JSON entity type and generates the ExtensionML necessary to render its interactive content. Symphony provides renderers for built-in data types and for third-party data types.
  • dialog: The Symphony dialog service that displays an interactive dialog. A dialog outputs ExtensionML.
  • share: The Symphony share service that shares content in Symphony conversations.

Experimenting with Messages using the PresentationML Live Renderer Tool

Symphony created the Presentation ML Live Renderer Tool that you can use to see your MessageML rendered in PresentationML or markdown (mobile) without coding.
For more information, refer to PresentationML Live Renderer Tool.

Message Identifiers

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 messageID is returned in the response.


  • 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 room ID, replace forward slashes with underscores, replace pluses with minuses, and ignore any trailing equal signs.

    Example: The URL Safe Base64 encoding of "4+0d8MktlTHpc+nlKgSBG3///qdSUAr+dA==" is "4-0d8MktlTHpc-nlKgSBG3___qdSUAr-dA".

Overview of Messages

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.