SMS API

Overview

Send SMS

The send SMS API enables an application to send an SMS on behalf of the user and check the delivery status of a sent SMS.

To can send a SMS just making an authorized request to Bluevia APIs with the recipient and origin addresses and the text of the message.

Bear in mind the following limitations when sending SMS:

SMS length is limited to 160 characters. Note that accented and special characters could count as two characters.
International SMS are not allowed. Note that your application sends SMS on behalf of the user, so it is allowed to send messages only to phone numbers belonging to the user's country.

Your application can send the same SMS to several users including multiple recipient address elements.

Check delivery status

There are two ways of checking the delivery status of a sent SMS:

Polling: Your application explicitly asks for the delivery status of a sent SMS.
Notifications: Your application requests to be notified about the delivery status of a sent SMS.

Regardless of the method you use to check delivery status, you could get the following delivery status information:

DeliveredToNetwork: The message has been delivered to the network. Another state could be available later to inform if the message was finally delivered to the handset.
DeliveryUncertain: Delivery status unknown.
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 another state.
DeliveredToTerminal: The message has been successful delivered to the handset.
DeliveryNotificationNotSupported: Unable to provide delivery status information because it is not supported by the network

Polling to check the delivery status

As stated above you can use Bluevia API to check the delivery status of a previous sent message. The delivery status of a sent SMS can be checked several times in order to get different status while the SMS is going through the network. When the SMS has been sent to multiple users the response to delivery status request includes as many delivery status elements as users the SMS was sent to.

Notifications to check the delivery status

If you provided a notification URL when sending the SMS you’ll receive a HTTP POST notification once the message has reached the final status. In this case please keep in mind the details about how notifications from Bluevia to the apps work (See the Authentication How to for more information http://link_to_howtos_authentication#when bluevia calls applications).

Note that although you are requesting delivery status notifications, you still are able to use the Location header to ask for delivery status following the polling strategy.

Receive SMS

This API enables an application to receive an SMS that the user sent to a shortcode. There are two ways of receiving the SMS in your application:

Polling: Your application explicitly asks for the incoming SMS.
Notifications: Your application requests to be notified each time a SMS is sent

Remember that users send SMS to your application sending a message to the [short number corresponding to their country http://link_to_shortcodes] and starting the message with the keyword you chose when requested the API key. Note that keywords are case-insensitive.

Bear in mind that your application doesn't need to run the OAuth process to get the user authorization to receive SMS, because this operation is not done on behalf of any user. You must use [2-legged OAuth http://link_to_howto/apiauth#application_not_acting_on_behalf_of_the_user]. This is an improvement in the latest versions of Bluevia APIs, but applications using 3-legged OAuth will keep working.

No matter how you receive the message you’ll get the origin address element containing either the phone number from which the message was sent, or an identifier (obfuscated sender) which represents the sender. This identifier can be used to answer the SMS.

Polling to receive SMS

To receive SMS messages sent to your application following a polling strategy make an authorized request indicating the short number corresponding to the user's country. Note that once your application has retrieved the messages, they are removed from the server.

Notifications to receive SMS

If you want to receive notifications about SMS sent to your applications you have to provide BlueVia with an URI where notifications must be sent. This URI is provided making a request to the inbound SMS subscription API. Please note that this subscription is for a specific shortcode and keyword. This creates a subscription to receive SMS sent to your application and in the response you’ll get a URL that can be used to stop receiving notifications.

Once your application has subscribed to received SMS notifications, BlueVia will send a notification to your application each time your application receives a SMS. This notification includes an Authorization header which should be used by your application to authenticate BlueVia (See the Authentication How to for more information http://link_to_howtos_authentication#when bluevia calls applications).

If you want to stop receiving notifications you have to unsubscribe your application making an authorized DELETE request to the URI you previously got during the subscription.

Operations

The following is the description of all operations, data types and error codes related to the SMS API. Data types are formally defined in the [SMS API XSD http://link_to_sms_schemas ](right click to download).

SendSMS

Allows an application to send a SMS.

Request

URI	https://api.bluevia.com/services/REST/SMS/outbound/requests?version=v1
HTTP method	POST
Authorization	OAuth [http://link_to_APIs_OAuth#Authenticated_API_Calls_From_Apps_to_Bluevia]
Body	smsText element of type SMSTextType, formatted as XML, JSON or URL encoded with the following structure: An address element containing the phone number to which this message is sent. You can also include the identifier (obfuscated sender) returned when receiving SMS as an alias element. You can include more than one address element in order to send the message to several recipients. A message element containing the message itself. An originAddress element containing the same access token used in the Authorization header. BlueVia is able to translate this access token to the users's phone number. This number will be shown in the handset which receives the message as sender number. • Receipt request: optional parameter used to request payment status notifications. It contains the URI where your application is expecting to receive the payment status notifications. Note that BlueVia only accepts HTTPS endpoints and the server certificate must be provided during the process of [requesting the API key http://link_to_/en/page/tech.howto.tut_APIkeys#get]. Besides it includes the correlator field, which is an application generated identifier for the SMS. This identifier will be included in the delivery status notifications for your application to correlate notifications with SMS.

Response

HTTP status	201 Created
HTTP headers	Location header, including the URI used to check delivery status.
Body	None

Example

Sending an SMS to one recipient:

POST /services/REST/SMS/outbound/requests?version=v1 HTTP/1.1 Content-Type: application/json Authorization: OAuth ... Host: api.bluevia.com:443  {"smsText": {   "address": {"phoneNumber": "524794786537"},   "message": "This is a text message",   "originAddress": {"alias": "4bf499a1ecaac050dfaddfef87f99e3a"}, }}

Or to many recipients:

{"smsText": {   "address": [     {"phoneNumber": "524794786537"},     {"phoneNumber": "527584789094"},     {"phoneNumber": "524750186732"}   ],   "message": "This is a text message",   "originAddress": {"alias": "4bf499a1ecaac050dfaddfef87f99e3a"} }}

Note that Authorization header has been trimmed for clarity.

And the response:

HTTP/1.1 201 Created Location: https://api.bluevia.com/services/REST/SMS/outbound/requests/10001022134544108250/deliverystatus Content-Length: 0

Check SMS Delivery Status

Allows an application to check the delivery status of a sent SMS.

Request

URI	Value of Location header from the Send SMS operation, followed by 'version=v1', and optionally 'alt=json' to request JSON format in the response.
HTTP method	GET
Authorization	OAuth [http://link_to_APIs_OAuth#Authenticated_API_Calls_From_Apps_to_Bluevia]
Body	None

Response

HTTP status	200 OK
Body	smsDeliveryStatus element of type SMSDeliveryStatusType, formatted as XML or JSON (if 'alt=json' was included in the request) with the following structure: An address element containing the phone number to which the message was sent. A deliveryStatus element with the delivery status information.

Example

GET /services/REST/SMS/outbound/requests/10001022134544108250/deliverystatus?version=v1&alt=json HTTP/1.1 Authorization: OAuth ... Host: api.bluevia.com:443

Response if the SMS was sent to one recipient:

HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8  {"smsDeliveryStatus":{   "smsDeliveryStatus":[{     "address":{"phoneNumber":"524794786537"},     "deliveryStatus":"DeliveredToTerminal"   }] }}

Or if it was sent to many recipients:

{"smsDeliveryStatus": {   "smsDeliveryStatus": [   {     "address": {"phoneNumber": "524794786537"},     "deliveryStatus": "DeliveredToTerminal"   },   {     "address": {"phoneNumber": "527584789094"},     "deliveryStatus": "DeliveredToNetwork"   },   {     "address": {"phoneNumber": "524750186732"},     "deliveryStatus": "DeliveryUncertain"   }] }}

Notify SMS Delivery Status Update

Allows BlueVia to notify your application about changes in SMS delivery status.

Request

URI	Value included in receiptRequest.endpoint from the Send SMS operation.
HTTP method	POST
Authorization	OAuth [http://link_to_APIs_OAuth#Authenticated_API_Calls_From_Bluevia_to_Apps]
Body	smsDeliveryStatusUpdate element of type SMSDeliveryStatusUpdateType, in the same format used in the Send SMS operation, that is, with the following structure: A correlator element containing the same value used during the SMS sending in the receiptRequest element. A deliveryStatus element containing: An address element containing the phone number the delivery status correspond to. A deliveryStatus element with the delivery status information

Response

HTTP status	204 No Content
Body	None

Example

The notification from Bluevia (note that it’s XML):

POST /myapp/receiveDeliveryStatus HTTP/1.1 Authorization: OAuth ... Content-Type: application/xml;charset=UTF-8 Host: mydomain.com:443  <?xml version="1.0" encoding="UTF-8"?> <NS1:smsDeliveryStatusUpdate xmlns:NS1="http://www.telefonica.com/schemas/UNICA/REST/sms/v1/">   <NS1:correlator>100000000207_1</NS1:correlator>   <NS1:deliveryStatus>     <NS1:address>       <NS2:phoneNumber xmlns:NS2="http://www.telefonica.com/schemas/UNICA/REST/common/v1">524794786537</NS2:phoneNumber>     </NS1:address>     <NS1:deliveryStatus>DeliveredToTerminal</NS1:deliveryStatus>   </NS1:deliveryStatus> </NS1:smsDeliveryStatusUpdate>

And the response from your application to Bluevia:

HTTP/1.1 204 No Content Content-Length: 0

Get Received SMS

Allows an application to get the received SMS sent to the application.

Request

URI	https://api.bluevia.com/services/REST/SMS/inbound/{registrationId}/messages?version=v1, optionally followed by 'alt=json' to request JSON format in the response, where {registrationId} is the [short number corresponding to the user's country http://link_to_short_codes].
HTTP method	GET
Authorization	OAuth
Body	None

Example

A sample request:

GET /services/REST/SMS/inbound/524040/messages?version=v1 HTTP/1.1 Authorization: OAuth ... Host: api.bluevia.com:443

Response

HTTP status

200 OK or 204 No Content (when no SMS are available).

Body

If there is any SMS available, a receivedSMS element of type SMSMesageType or ReceivedSMSType (depending if there is only one or more than one SMS), formatted as XML or JSON (if 'alt=json' was included in the request) with the following information:

A message element with the message text.
An originAddress element containing the phone number from which the message was sent. Note that in some countries, due to privacy reasons, you won't receive a phone number, but an identifier (obfuscated sender) which represents the sender. This identifier can be used to answer the SMS.
A destinationAddress element containing the short number to which the message was sent. Note that this short number includes the country code.
A destinationAddress element containing the short number to which the message was sent. Note that this short number includes the country code.
A dateTime element with the date and time when the message was sent.

A 204 No Content HTTP status with no body is also a right response, indicating that no messages have been received.

The response with one received message and obfuscated sender:

HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8  {"receivedSMS":{   "receivedSMS":[{     "message":"MYKEYWORD This is a text message",     "originAddress":{"alias":" D9191287D322B422F49ECC5223519737"},     "destinationAddress":{"phoneNumber":"524040"},     "dateTime":"2010-10-22T15:48:45.662Z"   }] }}

Or the body with more than one received message and non obfuscated sender:

{"receivedSMS": {   "receivedSMS": [   {     "message": "MYKEYWORD This is a text message",     "originAddress": {"phoneNumber": "524794786537"}     "destinationAddress": {"phoneNumber": "524040"},     "dateTime": "2010-10-22T15:46:08.937Z"   },   {

Subscribe to Received SMS

Allows an application to subscribe itself to receive notifications about received SMS sent to the application.

Request

URI	https://api.bluevia.com/services/REST/SMS/inbound/subscriptions?version=v1
HTTP method	POST
Authorization	OAuth
Body	smsNotification element of type SMSNotificationType, formatted as XML, JSON or URL encoded.

Example

The subscription to the notifications:

POST /services/REST/SMS/inbound/subscriptions?version=v1 HTTP/1.1 Authorization: OAuth ... Content-Type: application/xml; charSet=UTF-8 Host: api.bluevia.com:443  {"smsNotification": {     "reference": {       "correlator": "c7ke93abc4_2",        "endpoint": "https://mydomain.com/myapp/notifySmsReception"     },      "criteria": "MYKEYWORD",      "destinationAddress": {       "phoneNumber": "524040"     }   }}

Response

HTTP status	201 Created
HTTP headers	Location header, including the URI used to stop received SMS notifications (Unsubscribe to Received SMS operation).
Body	None

Example

The corresponding response:

HTTP/1.1 201 Created Location: https://api.bluevia.com/services/REST/SMS/inbound/subscriptions/c7ke93abc4_2 Content-Length: 0

Notify Received SMS

Allows BlueVia to notify your application when a new SMS sent to your applications is available.

Request

URI	Value included in reference.endpoint from the Subscribe to Received SMS operation.
HTTP method	POST
Authorization	OAuth
Body	receivedSMSAsync element of type ReceivedSMSAsyncType, in the same format used in the Subscribe to Received SMS operation.

Example

Once you are subscribed you’ll receive notifications like this one:

POST /myapp/notifySmsReception HTTP/1.1 Authorization: OAuth ... Content-Type: application/xml;charset=UTF-8 Host: mydomain.com:443  {"receivedSMSAsync": {     "message": {       "message": "MYKEYWORD This is a text message",        "originAddress": {         "phoneNumber": "524794786537"       },        "destinationAddress": {         "phoneNumber": "524040"       }     },      "correlator": "c7ke93abc4_2"   }}

Response

HTTP status	204 No Content
Body	None

Example

You’ll respond:

HTTP/1.1 204 No Content Content-Length: 0

Unsubscribe to Received SMS

Allows an application to unsubscribe itself from receiving notifications about received SMS sent to the application.

Request

URI	Value of Location header from the Subscribe to Received SMS operation, followed by 'version=v1'.
HTTP method	DELETE
Authorization	OAuth
Body	None

Example

In order to unsubscribe the request is:

DELETE /services/REST/SMS/inbound/subscriptions/c7ke93abc4_2?version=v1 HTTP/1.1 Authorization: OAuth ... Host: api.bluevia.com:443

Response

HTTP status	204 No Content
Body	None

Example

And the response:

HTTP/1.1 204 No Content Content-Length: 0