Restcomm API – SMS

SMS

An SMS represents an inbound or outbound SMS message. Using this API you can do things like:

  • Sending an SMS to a mobile number and optionally get notified of its delivery status

  • Sending a text message to a VoIP Restcomm Client, representing a registered software or hardware SIP phone.

  • Querying details for already exchanged SMS messages

Send SMS

POST /restcomm/2012-04-24/Accounts/{accountSid}/SMS/Messages

Sends a new SMS and returns its representation:

  • If the recipient of the SMS is a mobile number the message is routed to the mobile network and delivered to the mobile device.

  • If the recipient is a registered Restcomm Client then a SIP message is generated and routed to the VoIP client, provided that the Restcomm Client is registered. Notice that in this case the recipient client name needs to be prefixed with the string client: in the To parameter described below

Body Parameter Description

From

Phone number or short code to be used as the message sender. This number needs to be SMS-enabled in the Restcomm Platform (Required).

To

Phone number, short code or Restcomm client to which the message will be sent to. Needs to be in E.164 format in case of a phone number. In case of a Restcomm client, the client name needs to be prefixed with the string 'client:' (Required).

Body

Text body of the SMS message (Required).

StatusCallback

A URL for Restcomm Platform to send webhook requests to notify on any SMS delivery status event. Notice that StatusCallback is not applicable to messages addressed to Restcomm Clients. For more information check below (Optional).

Status Callback

The StatusCallback body parameter allows you to specify a URL where you can receive events in the form of HTTP POST requests (webhooks) with updates on SMS delivery status from the Restcomm Platform. Those requests can contain the following body parameters:

Body Parameter Description

MessageSid

Message Sid for the SMS that triggered this status callback request.

MessageStatus

Updated status for the SMS. The value is one of the following: sent, failed, delivered, undelivered. For more details please refer to the events description below.

ErrorCode

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

AccountSid

Account Sid for the account that sent the SMS that triggered this status callback request.

From

Sender of the SMS that triggered this status callback request.

To

Recipient of the SMS that triggered this status callback request.

Body

The text body of the SMS that triggered this status callback request.

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

  1. Sent status event, indicating whether Restcomm managed to successfully forward the SMS to the provider for further routing. The status is reflected on MessageStatus attribute described above and can be either sent on success or failed on failure. In case of failure no delivery status event is sent (see below).

  2. Delivery status event, indicating whether the provider managed to successfully deliver the SMS to the destination, given that the sent status event previously was sent. The status is reflected on MessageStatus attribute described above and can be delivered, undelivered or failed

Examples

Send an SMS message from 19876543212 to 13216549878 and also use a status callback URL so that you are notified of the SMS delivery status in the provided callback URL. Make sure that the provided callback URL is reachable from the internet:

$ curl -X POST https://<accountSid>:<authToken>@cloud.restcomm.com/restcomm/2012-04-24/Accounts/<accountSid>/SMS/Messages -d "From=19876543212" -d "To=13216549878" -d "Body=Test SMS from Restcomm" -d "StatusCallback=http://status.callback.url"

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":"19876543212",
  "to":"13216549878",
  "body":"Test SMS from Restcomm",
  "status":"sending",
  "direction":"outbound-api",
  "price":"0",
  "price_unit":"USD",
  "api_version":"2012-04-24",
  "uri":"/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/Messages/SM5dd70f7ea54e47f1a49749debeec3f7f.json"
}

Send a (SIP) message from 19876543212 to Restcomm Client alice. Notice the client: prefix in the To (remember that this client needs to be registered):

$ curl -X POST https://<accountSid>:<authToken>@cloud.restcomm.com/restcomm/2012-04-24/Accounts/<accountSid>/SMS/Messages -d "From=19876543212" -d "To=client:alice" -d "Body=Test SIP message from Restcomm" -d "StatusCallback=http://status.callback.url"

Example response:

{
  "sid": "SM0e164269a83c4d5ea331ed83fad5837c",
  "date_created":"Thu, 19 Nov 2015 07:21:35 -0500",
  "date_updated":"Thu, 19 Nov 2015 07:21:35 -0500",
  "account_sid":"ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "from":"19876543212",
  "to":"client:alice",
  "body":"Test SIP message from Restcomm",
  "status":"sending",
  "direction":"outbound-api",
  "price":"0",
  "price_unit":"USD",
  "api_version":"2012-04-24",
  "uri":"/restcomm/2012-04-24/Accounts/<accountSid>/SMS/Messages/SM0e164269a83c4d5ea331ed83fad5837c.json"
}

Get SMS List

GET /restcomm/2012-04-24/Accounts/{accountSid}/SMS/Messages

Returns a list of SMS records corresponding to SMS messages sent or received from the provided AccountSid, subject to the provided paging, filtering and sorting URL query parameters.

Paging

The following paging parameters are supported

Query Parameter Description

Page

Which page of SMS records to return, starting from 0.

PageSize

Number of records returned per page.

Filtering

The following filtering parameters are supported

Query Parameter Description

To

Only show messages addressed to this phone number or Client identifier.

From

Only show messages sent from this phone number or Client identifier.

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.

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.

Body

Only show messages that match this body text, partially or fully.

Sorting Information

Below you can find the supported sorting parameters. In order to use them 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’s the overall format: SortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of messages is sorted by the attribute in ascending order.

Query Parameter Description

DateCreated

Sort by date on which the message was sent.

From

Sort by the party who initiated the message.

To

Sort by the party who received the message.

Direction

Sort by the direction of the message.

Status

Sort by the status of the message.

Body

Sort by the text body of the message.

Price

Sort by the price of the message, if applicable.

Examples

The command below will return the first page of SMS records corresponding to SMS messages sent from '19876543212' to '13216549878' between 2018-05-30 and 2018-06-09, sorted by the creation date in ascending order:

$ curl -X GET  https://<accountSid>:<authToken>@cloud.restcomm.com/restcomm/2012-04-24/Accounts/<accountSid>/SMS/Messages.json?From=19876543212&To=13216549878&StartTime=2018-05-30&EndTime=2018-06-09&Page=0&PageSize=10&SortBy=DateCreated:asc

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": "19876543212",
            "to": "13216549878",
            "body": "Hello 13216549878",
            "status": "sent",
            "direction": "outbound-api",
            "price": "0.00",
            "price_unit": "USD",
            "api_version": "2012-04-24",
            "uri": "/2012-04-24/Accounts/<accountSid>/SMS/Messages/SM350df10671b64616a3bb92981967cecb.json"
        },
        ...
    ]
}

Get single SMS Information

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

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

Examples

Retrieve the information of the SMS record with Sid SM55ce5cf07b9649c283cbacab4dae56a9:

$ curl -X GET https://<accountSid>:<authToken>@cloud.restcomm.com/restcomm/2012-04-24/Accounts/<accountSid>/SMS/Messages/SM55ce5cf07b9649c283cbacab4dae56a9.json

Example response:

{
    "sid":"SM55ce5cf07b9649c283cbacab4dae56a9",
    "date_created":"Thu, 19 Nov 2015 07:21:24 -0500",
    "date_updated":"Thu, 19 Nov 2015 07:21:24 -0500",
    "date_sent":"2015-11-19T07:21:24.000-05:00",
    "account_sid":"ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "from":"19876543212",
    "to":"13216549878",
    "body":"Another test from Restcomm",
    "status":"sent",
    "direction":"outbound-api",
    "price":"0",
    "price_unit":"USD",
    "api_version":"2012-04-24",
    "uri":"/restcomm/2012-04-24/Accounts/<authToken>/SMS/Messages/SM55ce5cf07b9649c283cbacab4dae56a9.json"
}

SMS Attributes

The attributes of the SMS resource are as follows:

Attribute Description

Sid

A string that uniquely identifies the SMS Message.

DateCreated

The date on which this SMS Message was created.

DateUpdated

The date on which this SMS Message was last updated.

DateSent

The date on which the SMS was sent or received by Restcomm.

AccountSid

The AccountSid that sent or received this SMS message.

From

The phone number or short code that sent the message.

To

The phone number, short code or client that received the message.

Body

The text body of the SMS message.

Status

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

Direction

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

ApiVersion

The API version RestComm used to handle the SMS message.

Uri

The suffix for the HTTP resource, relative to the base organization url. For example when creating an SMS message using the endpoint https://cloud.restcomm.com/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/Messages.json, the Uri will be /2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/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.

Status Description

Here is a detailed breakdown of the Status attribute describing the current status of the SMS message:

Status Description

queued

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

sending

Restcomm has accepted the message and is sending it to the provider. Applies to outbound messages.

sent

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

failed

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

received

Restcomm has received the message. Applies to inbound message.

delivered

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

undelivered

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

SMS-specific error codes

In cases where an SMS fails to be delivered due to a Provider-related error

Code Message

30001

Queue overflow

30002

Account suspended

30003

Unreachable destination handset

30004

Message blocked

30005

Unknown destination handset

30006

Landline or unreachable carrier

30007

Carrier violation

30008

Unknown error

30009

Missing segment

300010

Message price exceeds max price