Message

A Message entity represents a sent or received message on any of the supported channels. Using this API you can send a message to multiple channels and get notified of its delivery status.

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.

In order to use the Messages API you need to open a support ticket for your account to be activated.

Channel Identities

The Messages API is built 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>"

Send Message

POST /api/2012-04-24/Accounts/{accountSid}/Messages

Sends a new message to a channel and returns its representation.The request contains a JSON body with the following content.

Channel providers support different capabilities. If a capability is not supported by a specific channel provider, the message status will be marked as failed, and the relevant callback URL will be invoked.

JSON Parameter Description

JSON Parameter	Description
from	(Required) The identity of the message sender on a specific channel. This parameter contains a channel URI, relative to the channel in the following format "<channelName>:<alphanumeric/pstnNumber>". E.g. `sms:+15553XXXXXX`, means the e164 number `+15553XXXXXX` on the SMS channel. Alphanumeric numbers are limited to 11 characters. Accepted characters include both upper and lower case ASCII letters, the digits from 0 to 9, and space: [A-Za-z0-9 ].
to	(Required) The identity of the message recipient on a specific channel. This parameter 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.
body	(Optional) Text body of the message. On some channels some restrictions may exist related to length of messages and splitting of long messages.
status_callback	(Optional) The status_callback body parameter lets you to specify 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. Those requests can contain the following body parameters.
status_callback_method	(Optional) The status_callback_method attribute allows you to specify which HTTP method CPaaS should use when requesting the URL in the status_callback attribute. Possible values are GET, POST. The default method is GET.
media_list	(Optional) An optional array of media attachments.
media_list.url	The HTTP URL pointing to the media attachment.
media_list.content_type	The MIME type for the media attachment.

from

(Required) The identity of the message sender on a specific channel. This parameter contains a channel URI, relative to the channel in the following format "<channelName>:<alphanumeric/pstnNumber>". E.g. sms:+15553XXXXXX, means the e164 number +15553XXXXXX on the SMS channel. Alphanumeric numbers are limited to 11 characters. Accepted characters include both upper and lower case ASCII letters, the digits from 0 to 9, and space: [A-Za-z0-9 ].

(Required) The identity of the message recipient on a specific channel. This parameter 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.

body

(Optional) Text body of the message. On some channels some restrictions may exist related to length of messages and splitting of long messages.

status_callback

(Optional) The status_callback body parameter lets you to specify 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. Those requests can contain the following body parameters.

status_callback_method

(Optional) The status_callback_method attribute allows you to specify which HTTP method CPaaS should use when requesting the URL in the status_callback attribute. Possible values are GET, POST. The default method is GET.

media_list

(Optional) An optional array of media attachments.

media_list.url

The HTTP URL pointing to the media attachment.

media_list.content_type

The MIME type for the media attachment.

Examples

Send a message with media attachment, from mms:+19876XXXXXX to mms:+13216XXXXXX and use a status callback URL so that you are notified of the message delivery status in the provided callback URL. Make sure the provided callback URL is reachable from the internet.

Example Request

curl -X POST https://company.com/api/2012-04-24/Accounts/ACCOUNT_SID/Messages  \
-d 'from=mms:+19876XXXXXX' \
-d 'to=mms:+13216XXXXXX' \
-d 'body=Test Message' \
-d 'status_callback=http://status.callback.url' \
-d 'media_list=[{"url":"https://example.com/image.jpeg","content-type":"image/jpeg"}]' \
-u 'YourAccountSid:YourAuthToken'

Example Response

{
  "sid": "SM5dd70f7ea54e47f1a49749debeec3f7f",
  "date_created":"Thu, 19 Nov 2015 07:21:35 -0500",
  "date_updated":"Thu, 19 Nov 2015 07:21:35 -0500",
  "account_sid":"ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "from":"mms:+19876XXXXXX",
  "to":"mms:+13216XXXXXX",
  "body":"Test Message",
  "status":"queued",
  "direction":"outbound-api",
  "api_version":"2012-04-24",
  "uri":"/api/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SM5dd70f7ea54e47f1a49749debeec3f7f.json",
  "media_list": [{"url":"https://example.com/image.jpeg","content-type":"image/jpeg"}]
}

Status Callback HTTP Parameters

Body Parameter	Description
MessageSid	Unique identifier of the message which triggered this status callback request.
MessageStatus	Updated status for the message. Possible values are: sending, sent, failed, delivered, undelivered. For more details please refer to the events description below.
ErrorCode	Error code associated with the sent message. The exact format of the error may depend on the provider (only present if an error occurred).
AccountSid	Account Sid of the account which sent the message that triggered this status callback request.
From	The identity of the message sender on a specific channel that triggered this status callback request. Example:. "sms:+15553XXXXXX".
To	The identity of the message recipient on a specific channel that triggered this status callback request. Example:. "sms:+15553XXXXXX".
Body	The text body of the message which triggered this status callback request.
MediaUrl	url of the media content attached in the message. This is an array parameter
MediaType	MIME type of media content attached in the message. This is an array parameter

Body Parameter

Description

MessageSid

Unique identifier of the message which triggered this status callback request.

MessageStatus

Updated status for the message. Possible values are: sending, sent, failed, delivered, undelivered. For more details please refer to the events description below.

ErrorCode

Error code associated with the sent message. The exact format of the error may depend on the provider (only present if an error occurred).

AccountSid

Account Sid of the account which sent the message that triggered this status callback request.

From

The identity of the message sender on a specific channel that triggered this status callback request. Example:. "sms:+15553XXXXXX".

The identity of the message recipient on a specific channel that triggered this status callback request. Example:. "sms:+15553XXXXXX".

Body

The text body of the message which triggered this status callback request.

MediaUrl

url of the media content attached in the message. This is an array parameter

MediaType

MIME type of media content attached in the message. This is an array parameter

Status CallBack Events

The following three events are supported, in the provided order:

Sending status event, indicating that CPaaS is trying to send the message to the channel provider for further routing
Sent status event, indicating whether CPaaS managed to successfully forward the message to the channel provider for further routing.The status is reflected on the MessageStatus attribute described above and can be either sent on success or failed on failure.
Delivery status event, indicating whether the channel provider managed to successfully deliver the message to the destination, given that the status event was previously sent. The status is reflected on the `MessageStatus attribute described above and can be delivered, undelivered or failed.

For more information on the statuses please refer to Status Description section.

Examples

Receive Delivery Status Callback for a message that was delivered to the end user.

Parameter	Value
from	mms:+16696002375
body	Welcome to the Omnichannel world!
to	mms:+12012547352
mediaUrl	https://company.com/api/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/MediaAttachments/bWVzc2FnaW5nLmJhbmR3aWR0aC5jb20vYXBpL3YyL3VzZXJzLzUwMDU2OTYvbWVkaWEvZTAxZjBhOWYtMTZiYi00MGM0LWE1YmEtMDlkNzc2MjU1NDY1LzEvdXNhLWJlc3QtcGxhY2VzLW1pYW1pLTUuanBnP2NoYW5uZWw9bW1z

Parameter

Value

from

mms:+16696002375

body

Welcome to the Omnichannel world!

mms:+12012547352

mediaUrl

https://company.com/api/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/MediaAttachments/bWVzc2FnaW5nLmJhbmR3aWR0aC5jb20vYXBpL3YyL3VzZXJzLzUwMDU2OTYvbWVkaWEvZTAxZjBhOWYtMTZiYi00MGM0LWE1YmEtMDlkNzc2MjU1NDY1LzEvdXNhLWJlc3QtcGxhY2VzLW1pYW1pLTUuanBnP2NoYW5uZWw9bW1z

Receive Message

To be able to receive messages, the phone number should be provisioned in CPaaS and linked to an application.

Some channel providers require to have the number provisioned and verified by them first. This action is taking place outside the CPaaS platform. Please contact your account manager to find out more about the process and set it up properly.

Please follow the Incoming Phone Numbers instructions to provision a new SMS or MMS omnichannel number and bind it to an application.

As the Message API is currently in Beta, the phone number is provisioned as a SIP number with SmsUrl reusing the existing capabilities. This will be subject to change before moving to General Availability.

When a message is sent from a customer to the number previously provisioned, CPaaS will send an HTTP callback to the SMSUrl provided in the Incoming Phone Number with the following request parameters. Based on those your application can decide how to process the inbound message. For example, you can reply with another message through the Message Verb RCML.

Incoming Message Request Parameters

Parameter Name	Description
AccountSid	Account Sid of the account that sent the message that triggered this callback request
From	The identity of the message sender on a specific channel that triggered this callback request. Example: "sms:+15553XXXXXX".
To	The identity of the message recipient on a specific channel that triggered this callback request. Example: "sms:+15553XXXXXX"
Body	The text body of the message which triggered this callback request.
MediaUrl	url of the media content attached in the message
MediaType	MIME type of media content attached in the message

Parameter Name

Description

AccountSid

Account Sid of the account that sent the message that triggered this callback request

From

The identity of the message sender on a specific channel that triggered this callback request. Example: "sms:+15553XXXXXX".

The identity of the message recipient on a specific channel that triggered this callback request. Example: "sms:+15553XXXXXX"

Body

The text body of the message which triggered this callback request.

MediaUrl

url of the media content attached in the message

MediaType

MIME type of media content attached in the message

For channels that support it the message will be marked as read as soon as the HTTP callback was replied to with a success response (200 OK), or failed otherwise.

Get Message List

GET /api/2012-04-24/Accounts/{accountSid}/Messages

Returns a list of message records corresponding to the messages sent or received from the provided AccountSid, subject to the provided paging, filtering and sorting URL query parameters. Only messages that reached a Delivery Status (delivered, undelivered, failed) will be retrieved.

Paging

The following paging parameters are supported

Query Parameter	Description
Page	Which page of omnichannel message records to return, starting from 0. A 400 response will be returned if this page doesn’t exist.
PageSize	Number of records returned per page.

Query Parameter

Description

Page

Which page of omnichannel message records to return, starting from 0. A 400 response will be returned if this page doesn’t exist.

PageSize

Number of records returned per page.

Additional Paging Information

The API returns URIs to the next, previous, first and last pages of the returned list as shown in the table below.

Request Parameters

Parameter	Description
Uri	The URI of the current page.
Firstpageuri	The URI of the first page of this list.
Nextpageuri	The URI of the next page of this list.
Previouspageuri	The URI of the previous page of this list.
Lastpageuri	The URI of the last page of this list.
NumPages	The total number of pages.
Total	The total number of items in the list.
Start	The position in the overall list of the first item in this page.
End	The position in the overall list of the last item in this page.

Parameter

Description

Uri

The URI of the current page.

Firstpageuri

The URI of the first page of this list.

Nextpageuri

The URI of the next page of this list.

Previouspageuri

The URI of the previous page of this list.

Lastpageuri

The URI of the last page of this list.

NumPages

The total number of pages.

Total

The total number of items in the list.

Start

The position in the overall list of the first item in this page.

End

The position in the overall list of the last item in this page.

Filtering

The following filtering parameters are supported.

Query Parameter	Description
To	Only show messages addressed to this recipient identity. This field supports prefix search, which lets you filter the records per specific channel as well.
From	Only show messages sent from this sender identity. This field supports prefix search, which lets you filter the records per specific channel as well.
StartTime	Only show messages that were sent or received on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. A 400 response will be returned if syntax is invalid.
EndTime	Only show messages that were sent or received on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. A 400 response will be returned if syntax is invalid.
Status	Only show messages with a given status value.
ErrorCode	Only show messages with a given error code value.
Body	Only show messages with a given body. The match will use a full-text search logic.

Query Parameter

Description

Only show messages addressed to this recipient identity. This field supports prefix search, which lets you filter the records per specific channel as well.

From

Only show messages sent from this sender identity. This field supports prefix search, which lets you filter the records per specific channel as well.

StartTime

Only show messages that were sent or received on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-05). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. A 400 response will be returned if syntax is invalid.

EndTime

Only show messages that were sent or received on this date/time or earlier, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-06T02:10:03) or, if you want to omit the time, YYYY-MM-DD (for example 2018-10-06). When only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in UTC timezone. A 400 response will be returned if syntax is invalid.

Status

Only show messages with a given status value.

ErrorCode

Only show messages with a given error code value.

Body

Only show messages with a given body. The match will use a full-text search logic.

Example Request

The following example filters MMS records sent to phone numbers starting with +1 prefix.

You will need to use a URL encoded format when specifying the phone number prefix in the API request. For example, mms:+1 encodes to mms:%2B1%25.

curl -X GET https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/Messages?To=mms:%2B1%25  \
   -u 'YourAccountSid:YourAuthToken'

const request = require('request');

// Provide your Account Sid and Auth Token from your Console Account page
const ACCOUNT_SID = 'my_ACCOUNT_SID';
const AUTH_TOKEN = 'my_AUTH_TOKEN';

request({
      method: 'GET',
      url: 'https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/' + ACCOUNT_SID + '/Messages?To=mms:%2B1%25',
      auth: { 'user': ACCOUNT_SID, 'pass': AUTH_TOKEN }
   },
   function (error, response, body) {
      // Add your business logic below; status can be found at 'response.statusCode' and response body at 'body'
      ...
   }
);

from http.client import HTTPSConnection
from base64 import b64encode

# Provide your Account Sid and Auth Token from your Console Account page
ACCOUNT_SID = 'my_ACCOUNT_SID'
AUTH_TOKEN = 'my_AUTH_TOKEN'

userAndPass = b64encode(bytes(ACCOUNT_SID + ':' + AUTH_TOKEN, 'utf-8')).decode("ascii")
headers = { 'Authorization' : 'Basic %s' %  userAndPass }

conn = HTTPSConnection('mycompany.restcomm.com')
conn.request("GET", '/restcomm/2012-04-24/Accounts/' + ACCOUNT_SID + '/Messages?To=mms:%2B1%25',
      headers=headers)
res = conn.getresponse()

# Add your business logic below; status can be found at 'res.status', reason at 'res.reason' and response body can be retrieved with res.read()
...

import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import java.io.*;
import java.util.Base64;

public class JavaSampleClass {
   // Provide your Account Sid and Auth Token from your Console Account page
   public static final String ACCOUNT_SID = "my_ACCOUNT_SID";
   public static final String AUTH_TOKEN = "my_AUTH_TOKEN";


   public static void main(String[] args) throws Exception {
      String userAndPass = ACCOUNT_SID + ':' + AUTH_TOKEN;
      String encoded = Base64.getEncoder().encodeToString(userAndPass.getBytes());

      URL url = new URL("https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/" + ACCOUNT_SID + "/Messages?To=mms:%2B1%25");
      HttpsURLConnection conn = (HttpsURLConnection)url.openConnection();
      conn.setRequestProperty("Authorization", "Basic " + encoded);
      conn.setRequestMethod("GET");

      // Add your business logic below; response code can be obtained from 'conn.getResponseCode()' and input stream from 'conn.getInputStream()'
      ...
  }
}

Example Response

{
"page": 0,
"num_pages": 0,
"page_size": 10,
"total": 5,
"limit": 5000,
"start": "0",
"end": "5",
"uri": "/api/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/SMS/Messages",
"first_page_uri": "/api/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/SMS/Messages?Page\u003d0\u0026PageSize\u003d10\u0026Limit\u003d5000",
"previous_page_uri": "null",
"next_page_uri": "null",
"last_page_uri": "/api/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/SMS/Messages?Page\u003d0\u0026PageSize\u003d10\u0026Limit\u003d5000",
"messages": [
{
"sid": "SM47dd8750872b4d0db873346993ce3527",
"date_created": "Tue, 10 May 2022 12:33:28 +0000",
      "date_updated": "Tue, 10 May 2022 12:33:28 +0000",
      "account_sid": "ACae6e420f425248d6a26948c17a9e2acf",
      "from": "mms:+12012XXXXXX",
      "to": "mms:+18016XXXXXX",
      "body": "echo:",
      "status": "delivered",
      "direction": "outbound-call",
      "num_segments": 1,
      "price": "0.0",
      "price_unit": "USD",
      "api_version": "2012-04-24",
      "uri": "2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Messages/SM47dd8750872b4d0db873346993ce3527.json"
    },
    {
      "sid": "SMe4798df9b634400c9410d8fbddd8f8ce",
      "date_created": "Tue, 10 May 2022 12:33:25 +0000",
      "date_updated": "Tue, 10 May 2022 12:33:25 +0000",
      "account_sid": "ACae6e420f425248d6a26948c17a9e2acf",
      "from": "mms:+18016XXXXXX",
      "to": "mms:+12012XXXXXX",
      "body": "",
      "status": "received",
      "direction": "inbound",
      "num_segments": 1,
      "price": "0.0",
      "price_unit": "USD",
      "api_version": "2012-04-24",
      "uri": "/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Messages/SMe4798df9b634400c9410d8fbddd8f8ce.json"
    },
    {
      "sid": "SM3222fbf5237a40b88a5ef3a88d118498",
      "date_created": "Tue, 10 May 2022 12:31:24 +0000",
      "date_updated": "Tue, 10 May 2022 12:31:25 +0000",
      "account_sid": "ACae6e420f425248d6a26948c17a9e2acf",
      "from": "mms:+12012XXXXXX",
      "to": "mms:+16696XXXXXX",
      "body": "echo: test form CPaaS",
      "status": "delivered",
      "direction": "outbound-call",
      "num_segments": 1,
      "price": "0.0",
      "price_unit": "USD",
      "api_version": "2012-04-24",
      "uri": "2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Messages/SM3222fbf5237a40b88a5ef3a88d118498.json"
    },
    {
      "sid": "SM1d022f995d834e27ae8b8fd0d16dd032",
      "date_created": "Tue, 10 May 2022 12:31:21 +0000",
      "date_updated": "Tue, 10 May 2022 12:31:21 +0000",
      "account_sid": "ACae6e420f425248d6a26948c17a9e2acf",
      "from": "mms:+16696XXXXXX",
      "to": "mms:+12012XXXXXX",
      "body": "Hello World!",
      "status": "received",
      "direction": "inbound",
      "num_segments": 1,
      "price": "0.0",
      "price_unit": "USD",
      "api_version": "2012-04-24",
      "uri": "/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Messages/SM1d022f995d834e27ae8b8fd0d16dd032.json"
    },
    {
      "sid": "SMb8951311a7df40bcbafad1294718c415",
      "date_created": "Tue, 10 May 2022 11:55:37 +0000",
      "date_updated": "Tue, 10 May 2022 11:55:51 +0000",
      "account_sid": "ACae6e420f425248d6a26948c17a9e2acf",
      "from": "mms:+12012XXXXXX",
      "to": "mms:+18016XXXXXX",
      "body": "Hello from CPaaS MMS Channel",
      "status": "delivered",
      "direction": "outbound-api",
      "num_segments": 1,
      "price": "0.0",
      "price_unit": "USD",
      "api_version": "2012-04-24",
      "uri": "2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Messages/SMb8951311a7df40bcbafad1294718c415.json"
    }
  ]
}

Sorting Information

The following sorting parameters are available. To use those you need to utilize the SortBy query parameter to determine which attribute you want to sort by and in which direction. Direction can either be 'asc' for ascending and 'desc' for descending sort ordering. Here is the proper format: SortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of messages is sorted by the attribute in ascending order. A 400 response will be returned if the syntax is invalid.

Query Parameter	Description
DateCreated	Sort by date on which the message was sent.
From	Sort by the party that initiated the message.
To	Sort by the party that received the message.
Direction	Sort by the direction of the message.
Status	Sort by the status of the message.

Query Parameter

Description

DateCreated

Sort by date on which the message was sent.

From

Sort by the party that initiated the message.

Sort by the party that received the message.

Direction

Sort by the direction of the message.

Status

Sort by the status of the message.

Examples

The command below will return the first page of records corresponding to omnichannel messages sent from 'sms:+19876XXXXXX' to 'sms:+13216XXXXXX' between 2018-05-30 and 2018-06-09, sorted by the creation date in ascending order.

Example Request

curl -X GET https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/Messages?From=sms:+19876XXXXXX&To=sms:+13216XXXXXX&StartTime=2018-05-30&EndTime=2018-06-09&Page=0&PageSize=10&SortBy=DateCreated:asc  \
   -u 'YourAccountSid:YourAuthToken'

const request = require('request');

// Provide your Account Sid and Auth Token from your Console Account page
const ACCOUNT_SID = 'my_ACCOUNT_SID';
const AUTH_TOKEN = 'my_AUTH_TOKEN';

request({
      method: 'GET',
      url: 'https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/' + ACCOUNT_SID + '/Messages?From=sms:+19876XXXXXX&To=sms:+13216XXXXXX&StartTime=2018-05-30&EndTime=2018-06-09&Page=0&PageSize=10&SortBy=DateCreated:asc',
      auth: { 'user': ACCOUNT_SID, 'pass': AUTH_TOKEN }
   },
   function (error, response, body) {
      // Add your business logic below; status can be found at 'response.statusCode' and response body at 'body'
      ...
   }
);

from http.client import HTTPSConnection
from base64 import b64encode

# Provide your Account Sid and Auth Token from your Console Account page
ACCOUNT_SID = 'my_ACCOUNT_SID'
AUTH_TOKEN = 'my_AUTH_TOKEN'

userAndPass = b64encode(bytes(ACCOUNT_SID + ':' + AUTH_TOKEN, 'utf-8')).decode("ascii")
headers = { 'Authorization' : 'Basic %s' %  userAndPass }

conn = HTTPSConnection('mycompany.restcomm.com')
conn.request("GET", '/restcomm/2012-04-24/Accounts/' + ACCOUNT_SID + '/Messages?From=sms:+19876XXXXXX&To=sms:+13216XXXXXX&StartTime=2018-05-30&EndTime=2018-06-09&Page=0&PageSize=10&SortBy=DateCreated:asc',
      headers=headers)
res = conn.getresponse()

# Add your business logic below; status can be found at 'res.status', reason at 'res.reason' and response body can be retrieved with res.read()
...

import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import java.io.*;
import java.util.Base64;

public class JavaSampleClass {
   // Provide your Account Sid and Auth Token from your Console Account page
   public static final String ACCOUNT_SID = "my_ACCOUNT_SID";
   public static final String AUTH_TOKEN = "my_AUTH_TOKEN";


   public static void main(String[] args) throws Exception {
      String userAndPass = ACCOUNT_SID + ':' + AUTH_TOKEN;
      String encoded = Base64.getEncoder().encodeToString(userAndPass.getBytes());

      URL url = new URL("https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/" + ACCOUNT_SID + "/Messages?From=sms:+19876XXXXXX&To=sms:+13216XXXXXX&StartTime=2018-05-30&EndTime=2018-06-09&Page=0&PageSize=10&SortBy=DateCreated:asc");
      HttpsURLConnection conn = (HttpsURLConnection)url.openConnection();
      conn.setRequestProperty("Authorization", "Basic " + encoded);
      conn.setRequestMethod("GET");

      // Add your business logic below; response code can be obtained from 'conn.getResponseCode()' and input stream from 'conn.getInputStream()'
      ...
  }
}

Example Response

{
    "page": 0,
    "page_size": 10,
    "total": 2,
    ...
    "messages": [
        {
            "sid": "SM350df10671b64616a3bb92981967cecb",
            "date_created": "Thu, 31 May 2018 16:10:32 +0000",
            "date_updated": "Thu, 31 May 2018 16:10:32 +0000",
            "account_sid": "<accountSid>",
            "from": "+sms:+19876XXXXXX",
            "to": "sms:+13216XXXXXX",
            "body": "Hello 13216XXXXXX",
            "status": "sent",
            "direction": "outbound-api",
            "api_version": "2012-04-24",
            "uri": "/2012-04-24/Accounts/<accountSid>/Messages/SM350df10671b64616a3bb92981967cecb.json"
        },
        ...
    ]
}

Get a Single Message Information

GET /api/2012-04-24/Accounts/{accountSid}/Messages/{MessageSid}

Returns detailed information for a single omnichannel message identified by the MessageSid path parameter in the URL.

Examples

Retrieve the information of the omnichannel message record with a Sid SM55ce5cf07b9649c283cbacab4dae56a9.

Example Request

curl -X GET https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/Messages/MESSAGE_SID  \
   -u 'YourAccountSid:YourAuthToken'

const request = require('request');

// Provide your Account Sid and Auth Token from your Console Account page
const ACCOUNT_SID = 'my_ACCOUNT_SID';
const AUTH_TOKEN = 'my_AUTH_TOKEN';
// Provide additional path parameters if applicable
const MESSAGE_SID = 'my_MESSAGE_SID'

request({
      method: 'GET',
      url: 'https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/' + ACCOUNT_SID + '/Messages/' + MESSAGE_SID + '',
      auth: { 'user': ACCOUNT_SID, 'pass': AUTH_TOKEN }
   },
   function (error, response, body) {
      // Add your business logic below; status can be found at 'response.statusCode' and response body at 'body'
      ...
   }
);

from http.client import HTTPSConnection
from base64 import b64encode

# Provide your Account Sid and Auth Token from your Console Account page
ACCOUNT_SID = 'my_ACCOUNT_SID'
AUTH_TOKEN = 'my_AUTH_TOKEN'
// Provide additional path parameters if applicable
MESSAGE_SID = 'my_MESSAGE_SID'

userAndPass = b64encode(bytes(ACCOUNT_SID + ':' + AUTH_TOKEN, 'utf-8')).decode("ascii")
headers = { 'Authorization' : 'Basic %s' %  userAndPass }

conn = HTTPSConnection('mycompany.restcomm.com')
conn.request("GET", '/restcomm/2012-04-24/Accounts/' + ACCOUNT_SID + '/Messages/' + MESSAGE_SID + '',
      headers=headers)
res = conn.getresponse()

# Add your business logic below; status can be found at 'res.status', reason at 'res.reason' and response body can be retrieved with res.read()
...

import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import java.io.*;
import java.util.Base64;

public class JavaSampleClass {
   // Provide your Account Sid and Auth Token from your Console Account page
   public static final String ACCOUNT_SID = "my_ACCOUNT_SID";
   public static final String AUTH_TOKEN = "my_AUTH_TOKEN";
   // Provide additional path parameters if applicable
   public static final String MESSAGE_SID = "my_MESSAGE_SID"

   public static void main(String[] args) throws Exception {
      String userAndPass = ACCOUNT_SID + ':' + AUTH_TOKEN;
      String encoded = Base64.getEncoder().encodeToString(userAndPass.getBytes());

      URL url = new URL("https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/" + ACCOUNT_SID + "/Messages/" + MESSAGE_SID + "");
      HttpsURLConnection conn = (HttpsURLConnection)url.openConnection();
      conn.setRequestProperty("Authorization", "Basic " + encoded);
      conn.setRequestMethod("GET");

      // Add your business logic below; response code can be obtained from 'conn.getResponseCode()' and input stream from 'conn.getInputStream()'
      ...
  }
}

Example Response

{
  "sid": "SM6c13cca264f940a4b4573a49e8bdf917",
  "date_created": "Thu, 4 Jul 2019 07:02:28 +0000",
  "date_updated": "Thu, 4 Jul 2019 07:02:33 +0000",
  "date_sent": "2019-07-04T07:02:28.000Z",
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "from": "sms:+4916543360736",
  "to": "sms:+4915739XXXXXX",
  "body":"Another test from CPaaS",
  "status": "delivered",
  "direction": "outbound-api",
  "num_segments": 1,
  "api_version": "2012-04-24",
  "uri": "2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SM6c13cca264f940a4b4573a49e8bdf917.json"
}

Message Attributes

The attributes of the omnichannel message resource are as follows:

Attribute Description

Attribute	Description
Sid	A string that uniquely identifies the Message.
DateCreated	The date on which this message was created.
DateUpdated	The date on which this message was last updated.
DateSent	The date on which the message was sent or received by CPaaS.
AccountSid	The AccountSid that sent or received this message.
From	Sender id that sent the message.
To	Recipient id that received the message.
Body	The text body of the message.
Status	The status of this message. Possible values are: `queued`, `sent`, `failed`, `received`, `delivered` and `undelivered`. For more information on the statuses please refer to Status Description section.
Direction	The direction of this message. Possible values are `incoming`, `outbound-api`, `outbound-call`.
ApiVersion	The API version CPaaS used to handle the message.
Uri	The suffix for the HTTP resource, relative to the base organization url. For example when creating an message using the endpoint \<<, the Uri will be `/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SM03dd468462814f20a28ea7be4cffac29.json`
error_code	Provides more information about failure reason in case message status is failed or undelivered. If not, it will be null.
error_message	Similar to error_code, but providing human-readable text.
num_segments	If the message is sent to PSTN and requires segmentation because of length, this will indicate number of segments. This is not available in POST response.

Sid

A string that uniquely identifies the Message.

DateCreated

The date on which this message was created.

DateUpdated

The date on which this message was last updated.

DateSent

The date on which the message was sent or received by CPaaS.

AccountSid

The AccountSid that sent or received this message.

From

Sender id that sent the message.

Recipient id that received the message.

Body

The text body of the message.

Status

The status of this message. Possible values are: queued, sent, failed, received, delivered and undelivered. For more information on the statuses please refer to Status Description section.

Direction

The direction of this message. Possible values are incoming, outbound-api, outbound-call.

ApiVersion

The API version CPaaS used to handle the message.

Uri

The suffix for the HTTP resource, relative to the base organization url. For example when creating an message using the endpoint \<<, the Uri will be /2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SM03dd468462814f20a28ea7be4cffac29.json

error_code

Provides more information about failure reason in case message status is failed or undelivered. If not, it will be null.

error_message

Similar to error_code, but providing human-readable text.

num_segments

If the message is sent to PSTN and requires segmentation because of length, this will indicate number of segments. This is not available in POST response.

Status Description

Here is a detailed breakdown of the Status attribute describing the status of the omnichannel message.

Status	Description
queued	CPaaS has queued the message pending transmission.Applies to outbound messages.
sent	CPaaS has already sent the message to the provider.Applies to outbound messages.
failed	Message failed processing either on the CPaaS or provider’s side.The reason could be that the message was expired, rejected or deleted by the provider.
received	CPaaS has received the message.Applies to inbound message.
delivered	The provider has delivered the message to the user’s terminal. Applies to outbound messages.
undelivered	The provider couldn’t deliver the message to the user’s Messages endpoint. Applies to outbound messages.

Status

Description

queued

CPaaS has queued the message pending transmission.Applies to outbound messages.

sent

CPaaS has already sent the message to the provider.Applies to outbound messages.

failed

Message failed processing either on the CPaaS or provider’s side.The reason could be that the message was expired, rejected or deleted by the provider.

received

CPaaS has received the message.Applies to inbound message.

delivered

The provider has delivered the message to the user’s terminal. Applies to outbound messages.

undelivered

The provider couldn’t deliver the message to the user’s Messages endpoint. Applies to outbound messages.