Skip to main content

Inbound SMS API v2.0.0

1. Introduction​

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

2. Terminology​

  • Inbound SMS Number Supplier - a mobile operator or other parties that deliver messages sent to Inbound SMS Service numbers to the SMS Platform.
  • Customer - the party to whom messages will be forwarded
  • Mobile subscriber - a person who 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 an application/x-www-form-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 payloads 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:

ParameterDescription
%sMobile 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
%rInbound number where SMS is received.
Example: 41763332600 (for inbound SMS service)
%tFull MO SMS text. Text content is encoded in UTF-8.
%UUnique 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.
%TTimestamp 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
%zCountry calling prefix of %s parameter.
Example: 41
%ZCountry ISO2 code of %s, ISO-3166-1 alpha-2 codes in upper case.
Example: CH
%XCountry ISO3 code of %s, ISO-3166-1 alpha-3 codes in upper case.
Example: CHE
%MPhone 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, the Customer needs 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 a 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:

NameDescription
idMessage ID (UUID format).
srcSource number (sender) in the international format.
dstDestination number (receiver) in the international format.
textMessage text.
receivedRFC 3339 formatted timestamp when the MO arrived at the system.

4.3 Response Codes​

The customer web server has to reply to 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 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 the customer service needs to send a reply (in the form of an MT message), it should be sent over the Bulk SMS HTTP Service.