MessageML v2 message format

When using APIs to 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.


Note: 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:

  • A maximum of 40 entities (hashtags, cashtags, and mentions)
  • A maximum of 2,500 unique tokens in the markdown representation of the message
  • A maximum of 81,130 characters of the encrypted markdown representation of the message

Note: 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, e.g. 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;

Note: Other XML named entity sequences such as &gt; may be used.


Valid Characters For Hashtags/Cashtags

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


Note: When sending numeric cashtags as signals, add an * after the $ sign, e.g. <messageML><cash tag="$*122450"/></messageML>

Please refer to this article for further information.