Inbound SMS API v2.0.0

1. Introduction

Inbound SMS Service provides real-time MO SMS forwarding to third-party system (Customer in the following text). MO messages are received, for example, on Global numbers.

2. Terminology

  • Inbound SMS Number Supplier - mobile operator or other parties that deliver messages sent to Inbound SMS Service numbers to the SMS Platform.
  • Customer - party to whom messages will be forwarded
  • Mobile subscriber - a person that sends SMS to Inbound SMS Service numbers using a mobile handset.

3. Technical Requirements

  • The customer must provide a standard HTTP(S) web server which can process one of the MO methods for notifications:

    • HTTP GET
    • HTTP POST request with www-urlencoded payload
    • HTTP POST request with JSON payload

  • The customer needs to provide the full URL of the script which will accept an incoming request. Parameter names in the URL can be defined by the customer.
    The list of available parameter values is defined below.

  • HTTP(S) request fields and JSON payload are encoded using UTF-8 encoding.

4. Parameters Available in HTTP Request

The customer has a choice of how to receive MO messages:

  • As a callback with the GET method
  • As a callback with the POST method, using www-urlencoded payload
  • As a callback with POST method, using JSON payload.

4.1 Sending MO Callback Notification Using GET or POST with www-urlencoded Payload

The SMS Platform does not require a fixed URL on the customer side to deliver the message. There are only a few parameters that are provided in the MO message, and the customer is free to decide which of them will be used and what the parameter name will be. The following parameters can be defined in the URL:

Parameter Description
%s Mobile phone of the user from which MO message is sent (message originator).
The number is in international format, leading + or 00 are not included.
Example: 41781234567
%r Inbound number where SMS is received.
Example: 41763332600 (for inbound SMS service)
%t Full MO SMS text. Text content is encoded in UTF-8.
%U Unique message ID on the SMS Platform side. Message ID is a UUID string with a length of 36 characters. UUID is represented by 32 hexadecimal digits, displayed in five groups separated by hyphens, in the form 8-4-4-4-12.
Example: 550e8400-e29b-41d4-a716-446655440000.
%T Timestamp when SMS was received by the SMS Platform. The parameter is in format YYYY-mm-dd HH:MM:SS.
Example:2013-11-22 10:05:03
%z Country calling prefix of %s parameter.
Example: 41
%Z Country ISO2 code of %s, ISO-3166-1 alpha-2 codes in upper case.
Example: CH
%X Country ISO3 code of %s, ISO-3166-1 alpha-3 codes in upper case.
Example: CHE
%M Phone number of the user mobile or not. Possible values: yes, no.

For example,

http://3rd.party.net/sms/accept?sender=%s&inboundnum=%r&text=%t&msgid=%U&country=%Z&countryprefix=%z&timestamp=%T

If needed, customer can encode in the URL its own parameters, for example:

http://3rd.party.net/sms/accept?sender=%s&inboundnum=%r&text=%t&msgid=%U&country=%Z&countryprefix=%z&timestamp=%T&service=Our+Inbound+Number+A

In this example, parameter service is the customer parameter that we pass to the URL.

In case of a POST request Customer need to provide:

  • URL:

    http://3rd.party.net/sms/accept

  • POST content (parameter names):

    sender=%s&inboundnum=%r&text=%t&msgid=%U&country=%Z&countryprefix=%z&timestamp=%T&service=Our+Inbound+Number+A

4.2 Sending MO Callback Notification Using POST with JSON Payload

In the case that the customer chooses to receive MO callbacks with JSON payload, each callback contains JSON object in the HTTP request body with the following format:

{
    "id": "d1ec69e2-bcfd-11ed-afa1-0242ac120002",
    "src": "41781234567",
    "dst": "41587000000",
    "text": "This is an MO",
    "received": "2006-01-02T15:04:05Z07:00"
}

Where parameters are:

Name Description
id Message ID (UUID format).
src Source number (sender) in the international format.
dst Destination number (receiver) in the international format.
text Message text.
received RFC 3339 formatted timestamp when the MO arrived at the system.

4.3 Response Codes

The customer web server has to reply on the HTTP request with the HTTP status code:

  1. HTTP 200 or 202 if the message is accepted for processing.
  2. Any HTTP 4xx or 5xx will be considered as a 'temporary failure' and the service will retry to deliver this message.

If an HTTP request cannot be performed because of network problems, delivery to the customer will be retried.

4.4 Handling Long/Concatenated MO SMS

If a mobile user sends a long MO that is transported as concatenated SMS, the SMS Platform will collect the parts and send only one MO callback with text fully assembled from the parts.

5. Sending MT Messages as a Reply

If customer service needs to send a reply (in form of an MT message) it should be sent over Bulk SMS HTTP Service.