Message

Overview

The <Message> verb allows your application to instruct CPaaS to send an outbound message to any of the supported Channels listed in the Messages API Overview.

A message can include various capabilities such as text body, pictures, audio, and other file types. See all supported channels and full list of capabilities per channel in the Messages API Overview.

If the message doesn’t comply with the Channel constraint, it will be marked as failed, and no billing will be applied for it.

Channel Identities

The Messages API is built on a top of the Channel Identity following the URI concept. URIs create a separate namespace for the different supported channels, thus providing an unique identity per Channel for the subscriber or business.

The following URIs are currently supported. More will be added as new channels become available:

  • "mms:<Number in e164 format>"

  • "sms:<Number in e164 format>"

Message Attributes

Name Allowed value Default value

from

The identity of the message sender on a specific channel. This attribute contains a channel URI, relative to the channel in the following format "<channelName>:<pstnNumber>". E.g. "sms:+15553XXXXXX" means the e164 number +15553XXXXXX on the SMS CHannel.

See below

to

The identity of the message recipient on a specific channel. This attribute contains a channel URI, relative to the channel in the following format "<channelName>:<pstnNumber>". E.g. "sms:+15553XXXXXX" means the e164 number +15553XXXXXX on the SMS CHannel.

See below

action

A relative or absolute URL address.

None

method

GET, POST

POST

statusCallback

A URL where you can receive events in the form of HTTP POST requests (webhooks) with updates of the Message delivery status from the CPaaS Platform.

none

statusCallbackMethod

GET, POST

POST

to

The 'to' attribute represents an Omnichannel URI. CPaaS will send a message to this channel identity. When sending a message during an incoming call, 'to' defaults to the calling party. When sending a Message during an outgoing call, 'to' defaults to the called party. The value of 'to' must be an Omnichannel URI. An example of MMS uri is: "mms:+15558XXXXXX".

from

The 'from' attribute represents an Omnichannel URI. When sending a Message during an incoming call, 'from' defaults to the calling party. When sending a Message during an outgoing call, 'from' defaults to the called party. If the CPaaS application is expecting the target user to reply to this outbound message, the From should match a corresponding IncomingPhoneNumber identity.

action

The 'action' attribute takes a URL address as an argument. After processing the <Message> verb, CPaaS will make a GET or POST request to this URL with the form parameters 'MessageStatus' and 'MessageSid'. Using an 'action' URL, your application can receive synchronous notification that the message was successfully enqueued or not.

If you provide an 'action' URL, CPaaS will use the RCML received in your response to the 'action' URL request to continue the current call. Any RCML verbs occurring after an <Message> which specifies an 'action' attribute are unreachable. If no 'action' is provided, <Message> will finish and CPaaS will move on to the next RCML verb in the document. If there is no next verb, CPaaS will end the phone call.

method

The 'method' attribute represents the value 'GET' or 'POST'. This tells CPaaS whether to request the 'action' URL via HTTP GET or POST method. This attribute is modeled after the HTML form 'method' attribute.

statusCallback

The statusCallback attribute allows you to specify a URL for CPaaS to send webhook requests to on each event of message delivery (triggered by status callbacks).

statusCallbackMethod

The statusCallbackMethod attribute lets you specify which HTTP method CPaaS should use when requesting the URL in the statusCallback attribute. The default is POST.

statusCallback Events

Event Possible status

sent

sent

completed

failed, delivered, undelivered

StatusCallback Parameters

Parameter Description Example value

MessageSid

The Sid of the message.

SMc5b1b09cf2b14ffe985461c3587f4c38

MessageStatus

The last status known for this message.

delivered

From

From address of the message (message sender).

sms:+19876XXXXXX

To

To address of the message (message receiver).

sms:+19876XXXXXX

Body

The message body.

Hello world

AccountSid

The Account Sid.

ACa272717421604a9d924a5837aa23711b

ErrorCode

Error code, if any. This parameter is optional.

30001

MediaUrl

There will be as many occurrences as media were attached.

http://company.com/pic.jpg

MediaType

There will be as many occurrences as media were attached.

image/jpeg

Nesting

The <Message> verb allows combination of <Body> and <Media> nouns. Only a single Body noun will be allowed. Multiple Media nouns are allowed.

The <Body> noun element contains the text of the message you want to send.

The <Media> noun element contains a URL of a media content to be sent. The <Media> noun element must also contain an attribute "contentType", for example "image/jpeg" of the media content.

If the <Body> and the <Media> nouns are absent then the server will get the <Message> element value as a message text (for backward compatibility).

The <Body> noun element must be before of all <Media> nouns.

Examples

Below is an example of how you can use the <Message> verb.

<Response>
    <Message>
        <Body>Hello World!</Body>
        <Media contentType="image/jpeg">http://company.com/pic.jpg</Media>
    </Message>
</Response>

The next RCML example showcases how you can use From, To and statusCallback parameters to send a message.

<Response>
    <Message from="sms:+19876XXXXXX" to="sms:+13216XXXXXX" statusCallback="http://status.callback.url" statusCallbackMethod="POST">
        <Body>Hello World !!!</Body>
    </Message>
</Response>