Message Format - MessageML v2

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 shorthand tags for embedding information (e.g. a mention) into a message. 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.

When creating or retrieving messages using the API, MessageML shorthand tags are translated into equivalent XHTML tags and returned in PresentationML.

Message size limits

Messages may include:

  • Maximum 40 entities (hashtags, cashtags, and mentions).
  • Maximum 2,500 unique tokens in the markdown representation of the message.
  • 81,130 characters of the encrypted markdown representation of the message.
    Note that there is a greater chance of reaching the token or the entity limit than the character limit.

šŸš§

XML formatting

MessageML is formatted as XML and should have all tags properly formatted. For example, rather than using <br> you must use <br/>.
For string attributes, standard rules for escaping XML special characters apply, i.e. escaping:

  • ' with &apos; (if single quotes are used to quote the value)
  • " with &quot; (if single quotes are used to quote the value)
  • < with &lt;
  • & with &amp;
    Other XML named entity sequences such as &gt; may be used.

šŸš§

Valid characters for hashtags and cashtags

Keywords may only contain alphanumeric characters, underscore, dot and dash.

Important: when sending numeric cashtags as signals, add an * after the $ sign, for example, $122450.
<cash tag="$
122450"/>

Root tag

MessageML messages are enclosed in a <messageML> tag. The following is a simple example:

<messageML>
  Hello <b>messageML</b> v2!
</messageML>

Handling Special Characters

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:

CharacterHTML escapingRequired escapingmessageML example
<&lt;Yes<messageML>&lt;</messageML>
&&#38;Yes<messageML>&#38; </messageML>
$&#36;Yes
The $ character only needs to be escaped if it comes before the { character.
<messageML>&#36;{}</messageML>
#&#35;Yes
The # character only needs to be escaped if it comes before the { character.
<messageML>&#35;{}</messageML>
>&gt;No<messageML>&gt;</messageML>
"&quot;No<messageML>&quot;</messageML>
'&#39;No<messageML>&#39;</messageML>
*&#42;No<messageML>&#42;</messageML>
%&#37;No<messageML>&#37;</messageML>

Content grouping

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

TagDescriptionOptional attributes
<p>paragraph</p>Paragraph formatting.* class
<hr />Horizontal rule.None.
<ul>
<li>list item</li>
</ul>
Unordered or bullet list.* class
<ol>
<li>list item</li>
</ol>
Numbered list.* class
<h1>, <h2>, <h3>, <h4>, <h5>, <h6>Heading text. 6 levels.* class
<div>paragraph</div>Block of text.
This tag can be used to specify visual styles, by adding a class attribute.
This tag is used to create Structured objects.
* This tag is also the root of any message read through the API.
class: color options.
data-entity-id
data-icon-src
data-accent-color
* See below for list of translated PresentationML attributes.

Text-level formatting and semantics

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

TagDescriptionOptional attributes
<br/>Insert a line break.None.
<a href="url">
Link Text
</a>
Insert a hyperlink that will be displayed in the message. href: the URL of the link
class: color options.
<b>text</b>Bold formatting.

Note: when receiving a message from an Agent that contains whitespace between the last character in a bolded section and the closing </b> tag, the bold section will be returned in Markdown (i.e. surrounded by double '*' characters) instead of XHTML tags.
* class: color options.
1.53 version onwards
<code>text</code>


1.52 and prior versions:
<code>text
</code>
Fixed-character formatting for code samples.

Note: 1.52 and prior versions require a line break before the closing </code> tag, otherwise, the content will not be rendered.
Also note that only up to 100 lines of code will be highlighted.
<i>text</i>Italics formatting.

Note: when receiving a message from an Agent that contains whitespace between the last character in an italics-formatted section and the closing </i> tag, the italics section will be returned in Markdown (i.e. surrounded by single '*' characters) instead of XHTML tags.
* class: color options.
<pre>
preformatted text
</pre>
Preformatted text. class: color options.
Non-HTML MessageML shorthand tags are not supported inside <pre>.
<span>text</span>No formatting.
This tag can be used to specify visual styles, by adding a class attribute.
This tag is used to create Structured objects.
class: color options.
data-entity-id
* See below for list of translated PresentationML attributes.

Tables and tabular data

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

TagsDescriptionOptional attributes
<table>
<tr>
<td>text</td>
</tr>
</table>
Render "text" in a table format. class
rowspan
* colspan
<thead>, <tbody>, <tfoot>Table sections.* class

Images and media

MessageML supports the following tags to embed media into messages:

TagsDescriptionAttributes
<img src="url"/>Image.
Images have a max height of 256px; otherwise, the default size is the size of the image.
For more information on how to send images through API call, refer to Sending images.
src
class
<audio/>Only supported for chime. See below. src
autoplay

Sending images

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.

ā€¢ Sending an image via the Create Message API using the image URL

$ curl -X POST https://yourpod.com/agent/v4/stream/:sid/message/create \
-H 'content-type: multipart/form-data' \
-H 'keyManagerToken: 01008e3fc538...5d82870985576' \
-H 'sessionToken: eyJhbGciOiJSU...6YmlWyim0peFkMA' \
-F 'message=<messageML>Sending attachment via API<img src="https://yourimg.com/test/myimage.svg"></img></messageML>'

ā€¢ Sending an image via Create Message API using Data URL (base64 encoding).
Note that it is necessary to include data:image/imageType+xml;base64 before the data string, as shown in the following example.

$ curl -X POST https://yourpod.com/agent/v4/stream/:sid/message/create \
-H 'content-type: multipart/form-data' \
-H 'keyManagerToken: 01008e3fc538...5d82870985576' \
-H 'sessionToken: eyJhbGciOiJSU...6YmlWyim0peFkMA' \
-F 'message=<messageML>Sending attachment via API<img src="data:image/svg+xml;base64,PHN2ZyBpZD0i...DcuMjcsMTYuN="></img></messageML>'

Shorthand tags

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

TagDescriptionOptional attributes
<mention uid="123456789"/>Insert a mention for the user whose Symphony userid is 123456789.
<mention email="[email protected]"/>Insert a mention for the user whose email address is [email protected]. strict=true, the API will throw an error if no user of that email address exists. (default)
strict=false . Message is accepted even if the user cannot be resolved.
<hash tag="label"/>Insert "label" as a hashtag.
<cash tag="ticker"/>Insert "ticker" as a cashtag.
Important: when sending numeric cashtags as signals, add a * after the $ sign, for example, $122450.

<messageML>
`<cash tag="$
122450"/> `
<chime />Send a chime message.
No other content is permitted with a <chime/> tag.
<card> (see example below)Inserts a card. iconSrc: image will be resized to 28 pixels by 28 pixels, use spacious mode.
(.jpg, .png and .gif)
accent: use background color values to select the accent color of the card.
<emoji shortcode="hearts">Inserts an emoji.For a list of available emojis, refer to Emojis.

The following is a example of a card tag that could be embedded into a message:

<card iconSrc="url" accent="tempo-bg-color--blue">
    <header>Card Header. Always visible.</header>
    <body>Card Body. User must click to view it.</body>
</card>

Structured objects
and tags

Structured objects are rich, inline, interactive components for Symphony messages that allow you to embed information that is more complex than simple text.

To create a message containing a Structured object, construct the message content using MessageML with either a <div> or a <span> element containing the following attributes:

  • class="entity": specifies that the message contains a corresponding structured object.
  • data-entity-id: the unique ID of the corresponding structure object.

This MessageML markup is then passed into the endpoint via the message parameter. The following examples show the use of the attributes in <div> and <span> respectively:

<div class="entity" data-entity-id="entityIdentifier">An object</div>
<span class="entity" data-entity-id="entityIdentifier">An inline object</span>

The examples above reference an entity object called entityIdentifier. The JSON corresponding to this object is passed to the create message endpoint via the data parameter. For example:

Data:
{
  "entityIdentifier": {
    "type": "org.symphonyoss.fin.security",
    "version": "0.1",
    "id": [{
      "type": "org.symphonyoss.fin.security.id.isin",
      "value": "US0378"
    },
      {
        "type": "org.symphonyoss.fin.security.id.cusip",
        "value": "037"
      },
      {
        "type": "org.symphonyoss.fin.security.id.openfigi",
        "value": "BBG000"
      }
    ]
  }
}

Style Attributes

Tags support the following style attributes where applicable:

background
background-attachment
background-blend-mode
background-clip
background-color
background-image
background-position
background-repeat
background-size
border
border-bottom
border-bottom-color
border-bottom-left-radius
border-bottom-right-radius
border-bottom-style
border-bottom-width
border-collapse
border-color
border-image
border-image-outset
border-image-repeat
border-image-slice
border-image-source
border-image-width
border-left
border-left-color
border-left-style
border-left-width
border-radius
border-right
border-right-color
border-right-style
border-right-width
border-spacing
border-style
border-top
border-top-color
border-top-left-radius
border-top-right-radius
border-top-style
border-top-width
border-width
box-shadow
box-sizing
caption-side
clear
color
content
counter-increment
counter-reset
display
empty-cells
font
font-family
font-kerning
font-size
font-size-adjust
font-stretch
font-style
font-variant
font-weight
height
letter-spacing
line-height
list-style
list-style-image
list-style-position
list-style-type
margin
margin-bottom
margin-left
margin-right
margin-top
max-height
max-width
min-height
min-width
opacity
outline
outline-color
outline-offset
outline-style
outline-width
overflow
overflow-x
overflow-y
padding
padding-bottom
padding-left
padding-right
padding-top
table-layout
text-align
text-align-last
text-decoration
text-decoration-color
text-decoration-line
text-decoration-style
text-indent
text-justify
text-overflow
text-shadow
text-transform
visibility
white-space
width
word-break
word-spacing
word-wrap

The following shows an example of using styles for an HTML table:

<table style="border-collapse:collapse;border:2px solid black;table-layout:auto;width:100%;background-color:#f2f2f2;box-shadow: 5px 5px">
    <thead>
        <tr style="background-color:#4D94FF;color:#ffffff;font-size:1rem" class="tempo-text-color-white tempo-bg-color-black\">
            <td style='text-shadow: 2px 2px black;border:1px solid blue;border-bottom: double blue;width:15%;text-align:center'>
                SUBJECT
            </td>
        </tr>
    </thead>
</table>

Standard Entities

This section lists the Structured Objects available for use in messages.

Article

FieldRequiredFormatDescription
titleYesStringThe headline of the article
subTitleNoStringThe subtitle of the article
blurbNoStringA summary of the article to display
dateNoUnix Epoch TimestampDate of publication
publisherNoStringName of the publisher
authorNoStringName of the author
thumbnailNoURL (could be a data url)Image to be displayed - 106x106px
idMust provide either id or href, or both.StringAn identifier used by the application to deeplink to the article
hrefMust provide either id or href, or both.URLURL to the article (opened in a new browser window)

Financial Objects

org.symphonyoss.fin.security

FieldRequiredFormatDescription
typeYesStringThe type of object. Must be set to org.symphonyoss.fin.security.
idYesArray of ObjectsAn array of one or more of the following objects:
org.symphonyoss.fin.security.id.ticker
org.symphonyoss.fin.security.id.isin
org.symphonyoss.fin.security.id.cusip
org.symphonyoss.fin.security.id.openfigi

More information about these objects is provided below.

org.symphonyoss.fin.security.id.ticker

FieldRequiredFormatDescription
typeYesStringThe type of object. Must be set to org.symphonyoss.fin.security.id.ticker.
valueYesStringThe name/ID of a ticker.

org.symphonyoss.fin.security.id.isin

FieldRequiredFormatDescription
typeYesStringThe type of object. Must be set to org.symphonyoss.fin.security.id.isin.
valueYesStringThe entity's ID.

org.symphonyoss.fin.security.id.cusip

FieldRequiredFormatDescription
typeYesStringThe type of object. Must be set to org.symphonyoss.fin.security.id.cusip.
valueYesStringThe entity's ID.

org.symphonyoss.fin.security.id.openfigi

FieldRequiredFormatDescription
typeYesStringThe type of object. Must be set to org.symphonyoss.fin.security.id.openfigi.
valueYesStringThe entity's ID.

Image

FieldRequiredFormatDescription
typeYesStringThe type of entity. Must be set to com.symphony.media.image.
versionYesStringThe version.
formatYesStringThe data format. Must be set to image.
urlYesStringThe URL of the image.

Taxonomy (mention)

FieldRequiredFormatDescription
typeYesStringThe type of object. Must be set to com.symphony.user.mention.
versionYesStringThe object's version.
idYesArray of objectsAn array of one or more of the following objects:
* com.symphony.user.userId

More information about these objects is provided below.

com.symphony.user.userId

FieldRequiredFormatDescription
typeYesStringThe type of object. Must be set to com.symphony.user.userId.
valueYesStringThe ID of a user.

Video

FieldRequiredFormatDescription
typeYesStringThe type of object. Must be set to com.symphony.media.video.
versionYesStringThe version.
formatYesStringThe video's format. Must be set to youtube or vimeo.
urlYesStringThe URL of the video.
idYesStringThe unique ID of the video (can be extracted from the video URL).

Symphony Elements

Symphony Elements is a collection of interactive elements that can be sent within messages to facilitate communication with Symphony users.

Through the use of the elements, bots can send messages that contain forms with text fields, dropdown menus, person selectors, buttons and more! To use the Elements, you just need to call the /agent/v4/stream/:sid/message/create API using the messageML v2 format. For more information and examples, refer to Overview of Symphony Elements.

Updated 5 months ago


Message Format - MessageML v2


Suggested Edits are limited on API Reference Pages

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