Skip to content

MessageML

You can use MessageML to implement conversational messaging with incoming message webhooks. MessageML is an XML-based set of instructions that you can use to respond to incoming SMS.

Example

MessageML is an XML document with a root <Response> element containing child action elements. For example:

<Response>
  <Message>Thanks for texting!</Message>
  <Redirect>do-next-action.php</Redirect>
</Response>

Actions

Actions are executed sequentially through the MessageML response. There are two actions available in MessageML.

Action: Message

The message action can be used to send a message. By default, it replies to the sender of the message you have received. You can configure the behavior of the message action with the following attributes.

Attribute Description Default
To The recipient of the message in E164 format. The sender of the incoming message being processed.
From The sender ID to use when responding. The phone number the message was received on.
ReplyUri The URI (absolute or relative) to send any replies to. The current URL.
StatusUpdateUri The URI (absolute or relative) to send Status Update Webhooks to. -

The content of the Message element is used as the body of the message.

A maximum of 10 message actions can be used in a MessageML response.

Example: reply to an incoming message

<Response>
  <Message>Thanks for texting!</Message>
</Response>

Action: Redirect

The redirect action can be used to transfer control of handling an incoming message to another URI. The contents of the Redirect element is used as the location to redirect to, and can either be an absolute or relative URI.

No further actions are executed after a redirect action.

A single incoming message can be redirected a maximum of 10 times.

Example: redirect to an alternative handler

<Response>
  <Redirect>/alternative-handler.php</Redirect>
</Response>

Cookies

Incoming message webhooks maintain cookies for up to 30 days between two parties in an SMS conversation. You can use cookies to easily maintain state in a conversation by either setting cookies directly, or using the in-built session state in your programming language or framework of choice.