MessageML describes the input which is accepted by the API Agent (the end point for Symphony's public message sending and receiving API). MessageML includes all valid PresentationML and is subject to the same general constraints, such as character encoding, the need for balanced tags and allowable styles, described in PresentationML.

The following MessageML tags are also accepted by the API Agent and will be translated into the indicated PresentationML and EntityJSON.

Permanent MessageML Elements

The following tags will be accepted by the API Agent and will be transliterated to the given standard tags:

MessageML	Equivalent PresentationML	Description
<mention email="user@domain" > <mention email="user@domain" strict="false" /> <mention uid="numericUserId" >	<span class="entity" data-entity-id="mention123456">@Pretty Name</span>	It is inconvenient for API callers to identify the correct numeric ID for a user when constructing a Mention (although API to find this from an email address does exist). It is also necessary for the pretty name provided in the PresentationML mention markup to be validated. For these reasons additional mention tags will be provided which will be mapped to equivalent PresentationML markup by the API agent. The optional attribute strict="true\|false" (defaulting to true) controls the behavior when the mentioned user can not be resolved. If strict="true", the API will throw an error. If strict="false", the convenience tag will be translated to plain text in the PresentationML.
`<chime/>`	<audio src="https://asset.symphony.com/symphony/audio/chime.mp3" autoplay="true"/>	A shorthand to allow a chime to be sent in a message.
<card iconSrc="url" class="barStyle" accent="blue"> <header>PresentationML</header><body>PresentationML</body></card>	<div class="card barStyle" data-icon-src="url" data-accent-color="blue"> <div class="cardHeader">PresentationML</div> <div class="cardBody">PresentationML</div> </div>	A card is a standard item in a message which has a number of visual elements and which can be opened and closed.

MessageML

Equivalent PresentationML

Description

<mention email="user@domain" >

<mention email="user@domain" strict="false" />

<mention uid="numericUserId" >

<span class="entity" data-entity-id="mention123456">@Pretty Name</span>

It is inconvenient for API callers to identify the correct numeric ID for a user when constructing a Mention (although API to find this from an email address does exist). It is also necessary for the pretty name provided in the PresentationML mention markup to be validated. For these reasons additional mention tags will be provided which will be mapped to equivalent PresentationML markup by the API agent.

The optional attribute strict="true|false" (defaulting to true) controls the behavior when the mentioned user can not be resolved. If strict="true", the API will throw an error. If strict="false", the convenience tag will be translated to plain text in the PresentationML.

<chime/>

<audio

src="https://asset.symphony.com/symphony/audio/chime.mp3"

autoplay="true"/>

A shorthand to allow a chime to be sent in a message.

<card iconSrc="url" class="barStyle" accent="blue">

<header>PresentationML</header><body>PresentationML</body></card>

<div class="card barStyle" data-icon-src="url" data-accent-color="blue">

<div class="cardHeader">PresentationML</div>

<div class="cardBody">PresentationML</div>

</div>

A card is a standard item in a message which has a number of visual elements and which can be opened and closed.

Transitional MessageML Elements

The following tags will be accepted by the API Agent for a transitional period and will be transliterated to the given standard tags:

Transitional Tag	Equivalent PresentationML
`<hash tag="tag"/>`	<span class="entity" data-entity-id="hash123">#tag</span>
`<cash tag="tag"/>`	<span class="entity" data-entity-id="cash456">$tag</span>

EntityJSON

The following MessageML tags will generate elements in the EntityJSON content when transliterated to PresentationML:

Convenience Tag	EntityJSON data
`<hash tag="tag"/>`	{"hash123": { "type": "org.symphonyoss.taxonomy", "version": "1.0", "id": [ { "type": “org.symphonyoss.taxonomy.hashtag", "value": “tag" } ] } }
`<cash tag="tag"/>`	{"obj123": { "type": "org.symphonyoss.fin.security", "version": "1.0", "id": [ { "type": “org.symphonyoss.fin.security.id.ticker", "value": “tag" } ] } }
`<mention email="user@domain"/>` `<mention uid="numericUserId"/>`	{"mention123456789": { "type": "com.symphony.user.mention", "version": "1.0", "id": [ { "type": “com.symphony.user.userId", "value": 123456789 } ] } }

Convenience Tag

EntityJSON data

<hash tag="tag"/>

{"hash123": {
        "type":     "org.symphonyoss.taxonomy",
        "version":  "1.0",
        "id": [
            {
                "type":     “org.symphonyoss.taxonomy.hashtag",
                "value":    “tag" 
            }
        ]
    }
}

<cash tag="tag"/>

{"obj123": {
        "type":     "org.symphonyoss.fin.security",
        "version":  "1.0",
        "id": [
            {
                "type":     “org.symphonyoss.fin.security.id.ticker",
                "value":    “tag"
            }
        ]
    }
}

<mention email="user@domain"/>
<mention uid="numericUserId"/>

{"mention123456789": {
        "type": "com.symphony.user.mention",
        "version":  "1.0",
        "id":  [
            {
                "type":     “com.symphony.user.userId",
                "value":    123456789
            }
        ]
    }
}

Template Macros

The API Agent will support Freemarker templating (see http://freemarker.org/). Any EntityJSON content associated with a message will be made available as the data model in the Freemarker interpreter and macros can then be used to expand the supplied MessageML document into a PresentationML document which fully describes the message.

This PresentationML represents the default rendering of the message, but where the receiving user has an App installed which is registered as a renderer for the type of some embedded complex object, that App will be called to render the data and the associated PresentationML will be ignored.