SMS
An SMS represents an inbound or outbound SMS message.Using this API you can perform the following actions:
-
Send an SMS to a mobile number and optionally get notified of its delivery status
-
Send a text message to a VoIP CPaaS Client, representing a registered software or hardware SIP phone
-
Query details for already exchanged SMS messages
Send SMS
POST /api/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 CPaaS Client then a SIP message is generated and routed to the VoIP client.Note that in this case the recipient client name needs to be prefixed with the string
client:
in theTo
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 CPaaS Platform (Required). |
To |
Phone number, short code or CPaaS 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 CPaaS 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 the CPaaS Platform to send webhook requests to notify on any SMS delivery status event. Note that StatusCallback is not applicable to messages addressed to CPaaS Clients. For more information check below (Optional). |
StatusCallbackMethod |
|
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 CPaaS Platform. Those requests can contain the following body parameters:
StatusCallbackMethod
The StatusCallbackMethod attribute allows you to specify which HTTP method CPaaS should use when requesting the URL in the StatusCallback attribute. The default is POST.
Status Callback HTTP 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:
-
Sent status event, indicating whether CPaaS 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). -
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://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/SMS/Messages.json \
-d 'From=19876543212' \
-d 'To=13216549878' \
-d 'Body=Test SMS' \
-d 'StatusCallback=http://status.callback.url' \
-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":"19876543212", "to":"13216549878", "body":"Test SMS", "status":"sending", "direction":"outbound-api", "api_version":"2012-04-24", "uri":"/api/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/Messages/SM5dd70f7ea54e47f1a49749debeec3f7f.json" }
Send a (SIP) message from 19876543212 to CPaaS Client alice
.Notice the client:
prefix in the To
(remember that this client needs to be registered):
curl -X POST https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/SMS/Messages.json \
-d 'From=19876543212' \
-d 'To=client:alice8' \
-d 'Body=Test SIP message' \
-d 'StatusCallback=http://status.callback.url' \
-u 'YourAccountSid:YourAuthToken'
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", "status":"sending", "direction":"outbound-api", "api_version":"2012-04-24", "uri":"/api/2012-04-24/Accounts/<accountSid>/SMS/Messages/SM0e164269a83c4d5ea331ed83fad5837c.json" }
Get SMS List
GET /api/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.
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 for the first page of this list. |
Nextpageuri |
The URI for the next page of this list. |
Previouspageuri |
The URI for the previous page of this list. |
Lastpageuri |
The URI for 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 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 |
EndTime |
Only show messages that were sent or received on this date/time or earlier, given as an ISO-8601 date/time string, like |
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 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.
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. |
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://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/SMS/Messages.json?From=19876543212&To=13216549878&StartTime=2018-05-30&EndTime=2018-06-09&Page=0&PageSize=10&SortBy=DateCreated:asc \
-u 'YourAccountSid:YourAuthToken'
Example response:
{ "page": 0, "page_size": 10, "limit": 10000, "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", "api_version": "2012-04-24", "uri": "/2012-04-24/Accounts/<accountSid>/SMS/Messages/SM350df10671b64616a3bb92981967cecb.json" }, ... ] }
The command below, usesLimit parameter to return a list of 500 records in total
curl -X GET https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/SMS/Messages.json?PageSize=10&Limit=500 \
-u 'YourAccountSid:YourAuthToken'
The result of the Limit parameter
{
"page": 0,
"num_pages": 3,
"page_size": 10,
"total": 34,
"limit": 1000,
"start": "0",
"end": "9",
"uri": "/api/2012-04-24/Accounts/ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/SMS/Messages",
"first_page_uri": "/api/2012-04-24/Accounts/ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/SMS/Messages?Page=0&PageSize=10&Limit=10000",
"previous_page_uri": "null",
"next_page_uri": "/api/2012-04-24/Accounts/ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/SMS/Messages?Page=1&PageSize=10&AfterSid=SM5e62e689fc204d41b6cfe4993a2d17cf&Limit=10000",
"last_page_uri": "/api/2012-04-24/Accounts/ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/SMS/Messages?Page=3&PageSize=10&Limit=10000",
"messages": [{
...
}]
}
Get single SMS Information
GET /api/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://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/SMS/Messages/MESSAGE_SID.json \
-u 'YourAccountSid:YourAuthToken'
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": "dev-test",
"to": "4915739360736",
"body":"Another test from CPaaS",
"status": "delivered",
"direction": "outbound-api",
"num_segments": 1,
"api_version": "2012-04-24",
"uri": "2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/Messages/SM6c13cca264f940a4b4573a49e8bdf917.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 CPaaS. |
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 |
Direction |
The direction of this SMS message. Possible values are |
ApiVersion |
The API version CPaaS 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 \<<, the Uri will be |
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 current status of the SMS message:
Status | Description |
---|---|
queued |
CPaaS 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 |
30010 |
Message price exceeds max price |
30090 |
No Response received for SMPP Request |