SMS RESTful API

SMS RESTful API

February 21, 2013

The OneAPI SMS interface allows a Web application to send and receive SMS messages. This is version 2 of the API, document version 1.3, published May 15th 2012

Resources and URIs

OneAPI Location may be accessed via a RESTful API. This utilises HTTP commands POST, GET, PUT, and DELETE in order to perform an operation on a resource at the server. This resource is addressed by a URI; and what is returned by the server is a representation of that resource depending on its current state.
POST, GET and DELETE are used in OneAPI SMS. The URIs of the resources are:

Sending SMS:

http://example.com/{api version}/smsmessaging/outbound/{senderAddress}/requests

  • Send an SMS message to one or more mobile terminals

http://example.com/{api version}/smsmessaging/outbound/{senderAddress}/requests/{requestId}/deliveryInfos

  • Query the delivery status of the SMS identified by requestId

http://example.com/{api version}/smsmessaging/outbound/{senderAddress}/subscriptions

  • Start and stop subscribing to delivery status notifications for all your sent SMS

Receiving SMS:

http://example.com/{api version}/smsmessaging/inbound/registrations/{registrationId}/messages

  • Retrieve SMS sent to your Web application (which is identified by registrationId)

http://example.com/{api version}/smsmessaging/inbound/subscriptions

  • Start and stop subscribing to notifications for SMS that have been sent to your Web application.

example.com is replaced by the hostname of the OneAPI server you are accessing. apiVersion optionally indicates the version of OneAPI SMS you are accessing – the default is the latest version supported by that server.

Request parameters

Please see the examples below for a description of the request parameters.

Representation formats

The SMS API supports application/x-www-form-urlencoded and application/JSON content types for POST operations. The response content type is application/JSON.

Examples : Sending Messages

Note the POST operations have been shown here as application/x-www-form-urlencoded . You can also use JSON in the request body, please see our Code examples.

Send an SMS from your Web application

Request:

POST http://example.com/1/smsmessaging/outbound/
tel%3A%2B12345678/requests HTTP/1.1
Host: example.com:80
Content-Type: application/x-www-form-urlencoded
Accept: application/json

address=tel%3A%2B13500000991&
address=tel%3A %2B13500000992&
senderAddress=tel:%2B12345678&
message=Hello%20World&
clientCorrelator=123456&
notifyURL=http://application.example.com/notifications/
DeliveryInfoNotification&
callbackData=some-data-useful-to-the-requester&
senderName=ACME%20Inc.
Use POST to create the SMS. The senderAddressin the URL must be URL-escaped.
Mandatory parameters
At least one address is the URL-escaped end user ID; in this case their MSISDN including the ‘tel:’ protocol identifier and the country code preceded by ‘+’. i.e., tel:+16309700001. OneAPI also supports the Anonymous Customer Reference (ACR) if provided by the operator.
Message (string) must be URL-escaped as per RFC 1738. Messages over 160 characters may end up being sent as two or more messages by the operator.
senderAddress is the address to whom a responding SMS may be sent
Optional parameters
clientCorrelator (string) uniquely identifies this create SMS request. If there is a communication failure during the request, using the same clientCorrelator when retrying the request allows the operator to avoid sending the same SMS twice.
senderName (string) is the URL-escaped name of the sender to appear on the terminal is the address to whom a responding SMS may be sent.
notifyURL (anyURI) is the URL-escaped URL to which you would like a notification of delivery sent. The format of this notification is shown below. callbackData (string) will be passed back in this notification, so you can use it to identify the message the receipt relates to (or any other useful data, such as a function name)

Successful response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: http://example.com/1/smsmessaging/outbound/
tel%3A%2B12345678/requests/abc123
Content-Length: 12345
Date: Thu, 04 Jun 2009 02:51:59 GMT

{"resourceReference": {"resourceURL":
"http://example.com/1/smsmessaging/outbound/
tel%3A%2B12345678/requests/abc123"}}

201 shows that the message was created. The Location header field shows the URI of the created message, including the senderAddress and requestID(‘abc123’) in the path. You can append ‘/deliveryInfos’ to this URI to query the delivery status (see below).For convenience this URI is also included in the response body as the resourceURL pair within the resourceReference object.

Query the delivery status of an SMS

Request:

GET http://example.com/1/smsmessaging/outbound/
tel%3A%2B12345678/requests/abc123/deliveryInfos HTTP/1.1
Accept: application/json
abc123 is the requestID which was returned in ‘create message’ response above.

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 04 Jun 2009 02:51:59 GMT

{"deliveryInfoList": {
    "deliveryInfo": [
        {   "address": "tel:+1350000001",
            "deliveryStatus": "MessageWaiting"},
        {   "address": "tel:+1350000999",
            "deliveryStatus": "MessageWaiting"}],
    "resourceURL": "http://example.com/1/smsmessaging/outbound/
tel%3A%2B12345678/requests/abc123/deliveryInfos"
}}

The deliveryInfoList object contains the delivery information for each address that you asked to send the message to, in a deliveryInfoarray.The deliveryStatus value may be one of:

  • “DeliveredToTerminal”, successful delivery to Terminal.
  • “DeliveryUncertain”, delivery status unknown: e.g. because it was handed off to another network.
  • “DeliveryImpossible”, unsuccessful delivery; the message could not be delivered before it expired.
  • “MessageWaiting” , the message is still queued for delivery. This is a temporary state, pending transition to one of the preceding states.
  • “DeliveredToNetwork”, successful delivery to the network enabler responsible for routing the SMS

The resourceURL is a reference to this response.

Subscribe to SMS delivery notifications

Request:

POST http://example.com/1/smsmessaging/outbound/
tel%3A%2B12345678/subscriptions HTTP/1.1
Host: example.com:80
Content-Type: application/x-www-form-urlencoded
Accept: application/json

notifyURL=http://www.yourURL.here&
criteria="GIGPICS"&
callbackData=doSomething()
Use POST to create the message subscription. The senderAddress in the URL must be URL-escaped.
Mandatory parameters:
notifyURL (URL) This will be used by the server to POST the notifications to you, so include the URL of your own listener application.
Optional parameters:
clientCorrelator (string) uniquely identifies this create subscription request. If there is a communication failure during the request, using the same clientCorrelator when retrying the request allows the operator to avoid creating a duplicate subscription.
criteria (string) Text in the message to help you route the notification to a specific application. For example you may ask users to ‘text GIGPICS to 12345′ for your rock concert photos application.
This text is matched against the first word, as defined as the initial characters after discarding any leading Whitespace and ending with a Whitespace or end of the string. The matching shall be case-insensitive.
callbackData (string) is a function name or other data that you would like included when the POST is received.

Response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: http://example.com/1/smsmessaging/outbound/
subscriptions/sub789
Date: Thu, 04 Jun 2009 02:51:59 GMT

{"deliveryReceiptSubscription": {
    "callbackReference": {
        "callbackData": "doSomething()",
        "notifyURL": " www.yourURL.here ",
        "criteria":"Urgent"
    },
    "resourceURL": "http://example.com/1/smsmessaging/
outbound/subscriptions/sub789 "}}

201indicates the subscription has been created at the URI in the Location header. ‘sub789’ indicates the subscription ID.The JSON response body simply confirms the creation of the subscription and the URL it will POST notifications to.

The format of the delivery receipt notification sent to your notifyURL is:

{"deliveryInfoNotification": {
    "callbackData": "12345",
    "deliveryInfo": {
        "address": "tel:+1350000001",
        "deliveryStatus": "DeliveredToNetwork"},
    }}
This will be sent for every SMS you have created. The deliveryStatus pair in the deliveryInfo object can take the values shown above in the ‘Query delivery status of an SMS’ example, except for ‘MessageWaiting’, since that is the initial status. The callbackData will also be passed back to you, echoing what you provided when you created a message to send (‘Send an SMS from your Web application’) or subscribed to delivery notifications.

Stop the subscription to delivery notifications

Request:

DELETE http://example.com/1/smsmessaging/
outbound/subscriptions/sub789 HTTP/1.1
Accept: application/json
Host: example.com:80
Make sure to use the correct subscriptionID in the URL.

Response:

HTTP/1.1 204 No Content
Date: Thu, 04 Jun 2009 02:51:59 GMT
Indicates request processed successfully but no data is returned

Examples : Receiving Messages

Retrieve messages sent to your Web application

Request:

GET http://example.com/1/smsmessaging/
inbound/registrations/3456/messages?maxBatchSize=2  HTTP/1.1
Host: example.com:80
Accept: application/json
‘3456’ is the registrationID agreed with the OneAPI operator.
Optional parameters:
maxBatchSize is the maximum number of messages to retrieve in this request

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 12345
Date: Thu, 04 Jun 2009 02:51:59 GMT

{"inboundSMSMessageList": {
    "inboundSMSMessage": [
        {   "dateTime": "2009-11-19T12:00:00",
            "destinationAddress": "3456",
            "messageId": "msg1",
            "message": "Come on Barca!",
            "resourceURL": "http://example.com/1/smsmessaging/
inbound/registrations/3456/messages/msg1",
            "senderAddress": "+447825123456"},
        {   "dateTime": "2009-11-19T12:00:00",
            "destinationAddress": "3456",
            "messageId": "msg2",
            "message": "Great goal by Messi",
            "resourceURL": "http://example.com/1/smsmessaging/
inbound/registrations/3456/messages/msg2",
            "senderAddress": "+447825789123"}
    ],
    "numberOfMessagesInThisBatch": "2",
    "resourceURL": "http://example.com/1/smsmessaging/
inbound/registrations/3456/messages",
    "totalNumberOfPendingMessages": "20"}}

The inboundSMSMessageList object contains an inboundSMSMessagearray with pairs detailing:

  • the dateTime that the message was received,
  • destinationAddress is the number associated with your service (for example an agreed short code, see ‘What do I need?’ above)
  • messageId is a server-generated message identifier
  • message is the SMS message itself
  • resourceURL is a link to the message
  • senderAddress is the MSISDN or Anonymous Customer Reference of the sender.

The remainder of the inboundSMSMessageList object are pairs indicating the numberOfMessagesInThisBatch, a self-referring resourceURL, and the totalNumberOfPendingMessages awaiting retrieval from gateway storage.

Subscribe to notifications of messages sent to your application

Request:

POST http://example.com/1/smsmessaging/
inbound/subscriptions HTTP/1.1
Host: example.com:80
Content-Type: application/x-www-form-urlencoded
Accept: application/json

destinationAddress=3456&
notifyURL=http://www.yoururl.here/notifications/
DeliveryInfoNotification&
criteria=Vote&
notificationFormat=JSON&
callbackData=doSomething()&
clientCorrelator=12345
Mandatory parameters
destinationAddress is the MSISDN, or code agreed with the operator, to which people may send an SMS to your application
notifyURL (URL) is your address to which notifications will be sent
Optional parameters
criteria (string) is case-insensitve text to match against the first word of the message, ignoring any leading whitespace. This allows you to reuse a short code among various applications, each of which can register their own subscription with different criteria.
notificationFormat is the content type that notifications will be sent in – for OneAPI v1.0 only JSON is supported.
clientCorrelator (string) uniquely identifies this create subscription request. If there is a communication failure during the request, using the same clientCorrelator when retrying the request allows the operator to avoid creating a duplicate subscription.
callbackData (string) is a function name or other data that you would like included when the POST is received.

Response:

 HTTP/1.1 201 Created
Content-Type: application/json
Location: http://example.com/1/smsmessaging/
inbound/subscriptions/sub678
Content-Length: 254
Date: Thu, 04 Jun 2009 02:51:59 GMT

{"resourceReference":
{"resourceURL": "http://example.com/1/smsmessaging/
inbound/subscriptions/sub678"}}

201indicates the subscription has been createdThe resourceURL pair in the resourceReference object indicates the URI of the newly created subscription.

The format of the message receipt notification sent to your notifyURL is:

{"inboundSMSMessageNotification": {
    "callbackData": "12345",
    "inboundSMSMessage": {
        "dateTime": "2009-11-19T12:00:00",
        "destinationAddress": "3456",
        "messageId": "mes1234",
        "message": "Vote for Mega Boy Band",
        "senderAddress": "+447825123456"
    }
}}

This will be sent for every SMS received (matching the optional criteria if provided). The inboundMessageNotification object includes any callbackData and an inboundSMSMessagearray with pairs detailing:

  • the dateTime that the message was received,
  • destinationAddress is the number associated with your service (for example an agreed short code, see ‘What do I need?’ above)
  • messageId is a server-generated message identifier
  • message is the SMS message itself
  • resourceURL is a link to the message
  • senderAddress sender’s MSISDN/Anonymous Customer Reference

Stop the subscription to message notifications

Request:

DELETE http://example.com/1/smsmessaging/
inbound/subscriptions/sub123 HTTP/1.1
Accept: application/json
Host: example.com:80
Make sure to use the correct subscriptionID in the URL.

Response:

HTTP/1.1 204 No content
Accept: application/json
Date: Thu, 04 Jun 2009 02:51:59 GMT
204 indicates the subscription has been deleted

Response codes and exceptions

HTTP response codes are used to indicate:
200 – Success!
201 – Created. The message resource was created and is being queued for delivery.
204 – No content
400 – Bad request; check the error message and correct the request syntax.
401 – Authentication failure, check your OneAPI provider’s authentication requirements.
403 – Forbidden; please provide authentication credentials.
404 – Not found: mistake in the host or path of the service URI.
405 – Method not supported: in OneAPI Location v1 only GET is supported.
503 – Server busy and service unavailable. Please retry the request.

More details on these at http://www.ietf.org/rfc/rfc2616.txt

Exceptions:

{"requestError": {
    "policyException": {
        "messageId": "POL0001",
        "text": "A policy error occurred. Error code is
maxBatchSize exceeded. The maximum allowed maxBatchSize is %1.",
        "variables": "20"  }
}}
400 indicates an error
The requestError object contains either a serviceException or a policyException object.
A serviceException describes the reason why the service cannot accept the request; for example if the registrationId was incorrect.
A policyException object means that the request syntax is valid, however an operator policy has been broken: in this example because the operator cannot support the batch size requested.
serviceException and policyException share the same body: an identifier pair for the exception (messageId), a text pair to describe it consistently (text), and a variables pair to indicate any specific cause of the error (variables). The variables relate to the %1 placeholder(s) in the text.

List of service exceptions for SMS:

Id Exception Text Variables
SVC0280 Message too long. Maximum length is %1 characters %1 – number of characters allowed in a message.
SCV0283 Delivery receipt notification not supported none

… also see the Common Service Exceptions that apply to all OneAPI APIs.

List of policy exceptions for SMS:

There are no policy exceptions unique to SMS, but plus see the Common Policy Exceptions that apply to all OneAPI APIs.

Reference Material

OneAPI is a profile (subset) of Parlay REST v1.0. The full specifications and guidelines may be found at: http://www.openmobilealliance.org/Technical/current_releases.aspx

Changelog

v1.3 May 17th 2012 Fixed incorrect resource URL for Querying message status

v1.2 March 26th 2012 Added the missing ‘maxBatchSize’ parameter from the OMA spec.

v1.1.1 March 22nd 2012 Minor change removing the reference to SOAP

v1.1 – expanded the range of HTTP error codes

Back
Contact GSMA Legal Email Preference Centre Copyright © 2014 GSMA. GSM and the GSM Logo are registered and owned by the GSMA.