Inbound SMS API

1. Introduction

The Inbound SMS Service provides real time MO SMS forwarding to 3rd party systems (Customer in following text). MO messages are received, for example, on Global numbers.

2. Terminology

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

3. Technical Requirements

  • You has to provide standard HTTP(S) web server which can process HTTP GET or HTTP POST request
  • You has to provide full URL of the script which will accept incoming request. Parameter names in URL can be defined by customer.
  • List of available parameter values is defined below.
  • HTTP(S) request fields are encoded using UTF-8 encoding
  • In case of HTTPS You can provide SSL certificate (physically or otherwise) so additional level of security can be achieved by checking is SSL certificate valid.

4. Required customer data

  1. URL as described in here
  2. Is URL receiving GET or POST, and in case of POST parameter names (content).
  3. Maximum number of retries (value N in here)
  4. Period between retries (value S in here)
  5. Timeout for completing HTTP(S) request to Customer URL (value T in here)
  6. Number of parallel requests that customer is able to handle concurrently
  7. Threshold and period of time for WARN and CRIT level (as described in here)
  8. MSISDNs and e-mail addresses, and HTTP(S) Push URL where to send problem notifications (as described in here)
  9. Timeout when to send notification to mobile subscriber that service is not available (as described in here)
  10. Text to send to mobile subscriber when service is not available (as described in here)
  11. Period how long to keep log files (as described in here)
  12. Number of digits N to be replaced in MSISDN (as described in here)
  13. Text for replacement (as described in here)

If there are multiple inbound numbers for customer, URL can be defined for each one of them separately.

5. Parameters available in HTTP request

HORISEN doesn't require a fixed URL on customer side in order to divert message. There are only few parameters which are provided in MO message, customer is free to decide which of them will be used and how the parameter name will be.

The following parameters can be defined in 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 is 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 HORISEN's side. Message ID is UUID string with 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.
For example 550e8400-e29b-41d4-a716-446655440000.
%T Timestamp when SMS was received by HORISEN. 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 Is mobile. 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 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 customer parameter that we pass to URL.

In case of 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

5.1 Response codes

On HTTP request customer web server has to reply with HTTP status code:

  1. HTTP 200 or 202 if message is accepted for processing.
  2. Any HTTP 4xx or 5xx will be considered as 'temporary failure' and HORISEN service will retry to deliver this message every S seconds, maximum N times. By default S=60, N=120.

If HTTP request cannot be performed because of network problems, or timeout T reached, delivery to customer will be retried and it will follow same retry scheme, retry every S seconds, maximum N times.

6. Sending MT messages as a reply

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

7. Problem notifications

7.1 Problem notification to Customer

All the issues related to malfunction of service, on HORISEN side and what is detected from HORISEN side on Customer side will be specified in details in separate document.

Possible problems:

  • HORISEN has problems receiving messages on inbound numbers assigned to customer. This is detected as:
    • Link is down
    • Other problem detected

  • HORISEN is unable to deliver multiple SMS to Customer. There will be two levels of alarms, WARN and CRITICAL. Parameters to define:

    • Threshold for WARN, how many problems within which period of time
    • Threshold for CRITICAL, how many problems within which period of time
    • MSISDNs where to send alarms by SMS, for each level
    • E-mail addresses where to send alarms by e-mail, for each level
    • TTP(S) Push URL where to send alarms by HTTP Push, for each level

Notification about service recovery will be sent to same channel (e-mail/SMS/HTTP Push) where original (WARN or CRITICAL) alarm notification is sent.

7.2 Problem notification to mobile subscriber

If Customer service cannot be reached within defined timeout of N seconds, to pass the received SMS, reply is sent back to mobile subscriber over Bulk Gate with message that service is unavailable.

Parameters to define:

  • How many seconds
  • Message text

8. Data obfuscation

Content, and MSISDN of the inbound messages will be obfuscated after delivering SMS to Customer. Message text will be replaced with predefined text. Last N characters of MSISDN will be replaced with characters ***. Message IDs** will not be overwritten and will be kept for problem solving as long as log files are kept.

Log files will be kept for period of time defined by Customer (max 3 months).