The XMessage specification is used by tools in the Communication package ecosystem. It is a subset of the far larger XMPP and also contains a few additional features not found in the XMPP specification.
The purpose of this specification is to provide a common message description standard that many different kinds of compatible tools can be based on. Using a single, shared message description standard has the following advantages:
- Users in the Communication package can mix and match tools and reassess which they use based on their changing needs. In particular, they don't get locked in to tools that may become deprecated or for which an attractive replacement becomes available.
- Tool implementors in the Communication ecosystem can benefit from feedback from a broad range of collaborators when designing new core functionality.
- Tool implementors in the Communication ecosystem can share core implementations.
- Enables building a message transport protocol between services.
This document is intended primarily for developers who build message processing engines (Transformers) or rule engines (Orchestrator).
The document assumes at least a fair understanding of XML. It is also useful to refer to XMPP for details about shared features. The same features can be built over json as well.
1.1 XML vs JSON
Even though JSON is tempting we chose XML for data interchange for the following reasons,
- Its is a document markup language which is what most of the text is for various modes of communication
- It has a schema and allows for validation of the same
- Building contracts among servers are a breeze
- It has namespaces which are used when combining different format. (Although we are not using namespaces right now, this spec will evolve into using namespaces for various sections as it expands)
The current structure of XMessages is divided into following sections.
- Sender/Reciever Information
- Channel/Provider Information
- Transformers that need to act on this message
- Context related parameters
- Message body
Let's dive deeper into all of these, but before that, this is the complete xml schema (this is used for validation currently)
2.1 Sender/Reciever Information
to construct uses the structure show below.
|Refers to if the response/reply from/to the user is from a bot or an actual user|
|Is for use case where the user or sever is sending the same message to multiple users or a single one|
|Current User ID; When the message is still not parsed, it could be his phone number but should generally be a UUID which represents the user in the database|
|ID of the conversation campaign the message is part of|
|Ff the reply is for a ODK Form based bot, this represents the ID of that form|
2.2 Channel/Provider Information
|Channel for the message (SMS, Email, WhatsApp etc)|
|Provider for the message (Gupshup, AmazonSES, Twilio, etc)|
2.3 Transformers that need to act on this message
Each message can be acted on by multiple transformers to modify/reply the payload/channel etc. This happens through
Transformers. Each transformer is assigned an ID when it is registered.
|Transformer's ID (genereated at the time of registration)|
|Meta data for the transformer|
2.4 Context related parameters
This section describes the
|App is a global namespace the message is part of. For example an app may correspond to multichannel conversation that many users are part of. Any segreation of conversation is defined as an app|
|Any of the following => |
|State of a message sent to the user. Any of the following => |
|Stage of the current conversation. Any of the following => |
|ID of the last message sent for this conversation thread.|
|The thread which the message belongs to|
2.5 Message body
Message body referes to the actual message body. The current list of message types includes plain text, xHTML, location, media, button choices, or a contactCard.
It describes the button choices to be included in payload.
An example of a list of button choices under payload are given below.
There are two supported protocols for message styling - XEP 0393 and XEP 0071. Note only message inside the
<text> are to be implemented with the following rules. All other tags are escaped. The common use cases and examples of messages are as follows:
Should be styled as => (Two spans, both )(alike in dignity)
Should be styled as => Everyone
Should be styled as => The full title is Twelfth Night, or What You Will but most people shorten it.
Text enclosed by a '`' (U+0060 GRAVE ACCENT) is a preformatted span SHOULD be displayed inline in a monospace font. A preformatted span may only contain a single plain span.
Should be styled as => Wow, I can write in
Any text inside of a block that is not part of another span is implicitly considered to be inside of a "plain text" span.
On rare occasions styling hints may conflict with the contents of a message. For example, if the user sends the emoji
"> _ <" it would be interpreted as a block quote. Senders may indicate to the receiver that a particular message SHOULD NOT be styled by adding an empty
3.7 Implementation Details
This document does not define a regular grammar and thus styling cannot be matched by a regular expression. Instead, a simple parser can be constructed by first parsing all text into blocks and then recursively parsing the child-blocks inside block quotations, the spans inside individual lines, and by returning the text inside preformatted blocks without modification.
It is RECOMMENDED that styling directives be displayed and formatted in the same manner as the text they apply to. For example, the string "emphasis" would be rendered as "emphasis".
This specification does not provide a mechanism for removing styling from individual spans or blocks within a styled message. Implementations are free to implement their own workarounds, for example by inserting Unicode non-printable characters to invalidate styling directives, but no specific technique is known to be widely supported.
To be updated based on incoming feedback. Feel free to write into firstname.lastname@example.org in case you have questions, feedback or want to know more!