Reference Turnkey Applications Tutorials Visual Designer
Reference Turnkey Applications Tutorials Visual Designer
    • REST API
      • Overview
      • API Endpoint
      • Authentication
      • Requests
      • Responses
      • Paging
      • Reason Codes Dictionary
    • Management APIs
      • Accounts
      • Identity Access Management BETA
        • Identity Access Management Overview
        • Identity Access Management API
          • User Management
            • Create a User
            • Update a User
            • Retrieve a User
            • Delete a User
          • API Keys Management
            • Create an API Key
            • Update an API Key
            • Retrieve an API Key
            • Delete an API Key
      • Applications
      • Clients
        • Create a Client
        • Delete a Client
        • Change Client’s Password
        • Get a List of Available Clients
      • Incoming Phone Numbers
        • IncomingPhoneNumber Instance Resource
        • IncomingPhoneNumbers List Resource
        • Local IncomingPhoneNumber Factory Resource
        • Toll-Free IncomingPhoneNumber Factory Resource
        • Mobile IncomingPhoneNumber Factory Resource
        • Attach a phone number to an application
        • Enable Incoming MMS for an Application
        • Delete a phone number
        • List of Phone Numbers
        • Incoming Phone Number Regex Support
      • Notifications
      • Usage Records
      • Trace Records
    • Voice
      • Calls
        • Call List Resource URI
        • Making a Call
        • Modifying Live Calls
        • Examples
        • List Filter
        • Paging Information
      • Conference Management
        • Supported Operations
        • Conference List Resource URI
      • Conference Participants Management
        • Participants List Resource URI
      • Gather DTMF
      • Gather Speech
      • Say
      • Play
      • Hold
      • Recordings
      • Refers
        • Resource Properties
        • Supported Operations
        • Paging Information
      • Resume
      • SIP Refer Support
    • Messages API - BETA
      • Overview
      • Channel Identities
      • Send Message
      • Status Callback Parameters
      • Status Callback Events
      • Receive Message
        • Incoming Message Request Parameters
      • Get Message List
      • Get Single Message
      • Message Attributes
      • Status Description
    • SMS
      • Messages
        • Send SMS
        • Get SMS List
        • Get single SMS Information
        • SMS Attributes
      • Error Codes
    • Email
    • RCML
      • Overview
        • Interacting with Your Application
        • RCML Verbs
      • Dial
        • Client
        • Conference
        • Number
        • SIP
      • Email
      • Gather
      • Say
      • Play
      • SMS
      • Message - Beta
      • Hold
      • Resume
      • Hangup
      • Pause
      • Redirect
      • Record
      • Reject
      • Refer
    • Visual Designer API
      • List Application Templates
      • :List a Specific Application Template
      • Create a Visual Designer Application
      • Get Application Details
      • Save Application Changes
      • Create Application Parameters
      • List Application Parameters
      • Delete Application Parameters
      • Upload Application Media Files
      • List Application Media Files
      • Play Application Media Files
      • Delete Application Media Files
      • Get Application Logs
      • Delete Application Logs
      • Get Application Settings
      • Modify Application Settings
      • Rename an Application
      • Delete an Application
      • Get Visual Designer Configuration
    • Turnkey Apps APIs
      • Smart 2FA
        • Sending One-Time Passwords
        • Verifying One-Time Passwords
        • Cancel One-Time Passwords
        • Session Detail Record (SDR)
        • Get list of One-Time Passwords
        • Get a Single One-Time Password
        • Usage Record One-Time Passwords
        • Common Response Error Code
        • Limit
          • Create Limit
          • Update Limit
          • Delete Limit
          • Get List of Limits
      • Call Queuing
      • Auto Attendant
        • Users
        • Announcement
        • Auto Attendant System
        • Menu
        • Schedule
        • Phone Number
        • Usage Records
        • Third Party Integration
      • Number Masking
        • Application
        • Mask Number Pool
        • Context
        • Participants
        • Interactions
        • Usage Records
      • Task Router
docs 1.0
  • docs
    • 1.0
  • docs
  • Enterprise:Messages API - BETA
  • Enterprise:Overview

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

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.

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

Status CallBack Events

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

  1. Sending status event, indicating that CPaaS is trying to send the message to the channel provider for further routing

  2. 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.

  3. 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

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

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.

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.

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.

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.

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

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.

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.

Platform

Programmable Voice

Programmable SMS

Turnkey Applications

Smart 2FA

Call Queue

Auto Attendant

Number Masking

Task Router

Campaign Manager

Learn

Terms And Conditions

About

ABOUT

CONTACT US

© 2020, All rights reserved.