Premium Transit API

Introduction

MO-MT SMS Transmission System provides receiving of MO (Mobile Originated) SMS messages and sending of MT (Mobile Terminated) SMS messages via standard HTTP protocol.

Optionaly the session handling of MO messages is supported, see Appendix A for details.

Technical Requirements

  1. In order to receive the MO messages, customer need to provide to HORISEN the following:
    • Server: http://<host_ip>:<port>/<script_path>
    • Protocol: HTTP POST;
      HORISEN will provide static IP address the MO messages coming from (for security reasons).
  2. In order to receive the MT messages from customer, HORISEN will provide:
    • Server: http://<HORISEN_host_ip>:<port>
    • Protocol: HTTP POST;
      Customer also has to provide static IP address the MT requests will coming from.

Every submission (from HORISEN to customer or from customer to HORISEN) must be confirmed by XML status report.

The text content is encode by ISO-8859-1 codepage, and characters which is not supported by mobile phones will be replaced with space character.

Parameters for Receiving MO Messages

Available parameters:

ParameterMandatoryDescription
short_id YES The Short ID number.

Example: short_id=919
from YES The end user phone number, the number is always in international format
(without leading + or 00).

Example: from=41781234567
text YES Content of the message.

Example of text SMS: text=test Hello, this is the test message.
Provider YES SMS/GSM operator name.

example: provider=SWISSCOM
keyword YES Keyword name is used to indicate the service, the format is: KW_name@ShortID. The keyword is the first word in text of the massage (see parameter text).

Example: TEST@919
message_id YES The unique MO message ID in our system. 3rd party can use this parameter to be sure to avoid MO duplicates due MO resending scheme (MO’s are resent only in case that there is no connection to 3rd party server). Type of parameter is 32bit integer.

Example: message_id=453248
language NO MO message language (if known), type is char(2)

possible values: DE, FR, IT, EN

example: language=DE
session_id NO The session ID identifier in case that mobile user is in session. When session is started on certain keyword, all further MO messages are routed to this keyword until session expires or until it is stopped. Sessions are usually used in chat services.

session_id=23543
session_status NO Current session status indicator. It is delivered with every MO message during active session, at the same time session_id is also valid.

Possible values are: C, A or S
C(reated) appears only on 1st SMS which creates session
A(ctive) indicates that session is running
S(topped) appears only on last SMS when session is stopped

example: session_status=A

Mandatory Parameters for Sending MT Messages

Required parameters:

ParameterMandatoryDescription
account YES The customer’s account ID (provided by HORISEN)
username YES The customer’s username (provided by HORISEN)
password YES Provided by HORISEN
short_id YES The Short ID number.

Example: short_id=919
to YES The end user phone number, the number is always in international format
(without leading + or 00).

Example: from=41781234567
text YES Content of the message – text format (max 160 signs) or binary data in hexadecimal (in this case the udh parameter must exists).
The optional parameter coding (see next table) indicates how text is encoded.

Example of text SMS:
text=Hello world.

Example of binary SMS:
text=02004001b2055059064a3a51d195cdd105605...
provider YES SMS/GSM operator

example: provider=SWISSCOM
keyword YES Keyword is used to indicate the unique SMS service name, the format is: KW_NAME@ShortID

example:TEST@919
price YES The price of the message. Range of this parameter depends on country. The price parameter is always integer, so in countries where price can be fractioned it should be always multiplied with 100.
In Switzerland price can vary from 0,00 to 3,00 CHF, so it is fractioned and price parameter is in range 0-300 (the service price multiplied by 100).

Example for price of 0,60 CHF:
price=60

Optional Parameters for Sending MT Messages

Optional parameters:

ParameterMandatoryDescription
udh NO User Data Header of the SMS message, it is always in binary format.

Example of udh header:
udh=06050415810000
coding NO Coding scheme of parameter text. If udh exists coding is 1 by default. Use coding=0 only in case of concatenated messages where udh exists but text is not binary

possible values:
0 for textual coding
1 for binary coding

example: coding=0
price_code NO There are the special cases when operators define implicit charging (during ABO starting or stopping, in case of wrong keyword, etc.). In these cases price parameter has to be 0 and price_code indicates special case type. The end user price depends on special case type and operator, but this is out of our consideration.

Possible values:
START, STOP, STOP_ALL, VIEW, INFO, INDEX, HELP or WRONG_KWORD

example: price=0&price_code=START

important: when you use price_code, price has to be 0
ext_id NO 3rd party’s unique message id which will be forwarded in delivery report. Maximum length is 30 characters.

Example: ext_id=ab23635c5d
bill_info NO Some operator provide information about SMS service name on bills sent to their customers. The SMS service name is provided by SMS provider (HORISEN), but in exceptional cases 3rd party can override default value. Maximum length is 20 characters

example: bill_info=start test
session_id NO If SMS session is active or temporarily blocked, then 3rd party can change its status by MT message. This is usually used for stopping session by 3rd party. Session_id has to mach session_id delivered in MO request.
session_status NO The new session status which will affect next MO message.

Possible values are: A or S
A(ctivate) indicates that session should be activated
S(top) indicates that session should be stopped

example: session_status=S

XML Submission Response

The response for message submission (between both servers) is in XML format. The most important is tag which indicates is request successfully delivered or not.

Reply of 3rd party on MO request sent by HORISEN

Value of the tag status can be success or anything else (then we consider it like a failure). It is very important for 3rd party to send to us submission response otherwise we will assume that MO message is not delivered to 3rd party (this can lead to repetitive submission of the same MO if retry scheme is active).

The reply which has to be provided by 3rd party is very simple.

<?xml version="1.0"?>
<report>
	<status>success</status>
</report>

Reply of HORISEN on MT request sent by 3rd party

The reply from HORISEN’s side is very similar to already described form. Beside status tag we will always offer some additional information. Let’s see how accepted MT message will be confirmed (the msg_id tag indicates our internal Id of MT message):

Possible reply:

<?xml version="1.0"?>
<report>
	<status>success</status>
	<msg_id>65343</msg_id>
</report>

The rejected MT message is more descriptive:

<?xml version="1.0"?>
<report>
	<status>error</status>
	<error_code>X</error_code>
	<error_desc>The description of the error</error_desc>
</report>

error_code is integer and it is predicted for machine parsing

error_desc is human readable error description

At the moment we have defined following errors:

error_codeerror_desc
1 Authorization failed.
2 Invalid international phone number.
3 Wrong provider name.
4 Wrong short id.
5 The text parameter is missing or it is too long.
6 Wrong end user price.
7 The maximum message count in time (per user) is exceeded.
8 WSI is longer than single SMS. Please, make shorter text or wsi_url.
9 User is not subscribed on service any more.
97 Wrong keyword.
98 Message submission to the SMS gate failed.
99 Internal error.

Delivery Reports

There are cases when 3rd party needs information about MT SMS delivery because with MT billing only delivered messages are charged. HORISEN provides additional HTTP request which is sent at the moment when we get DLR information from operator. This request can happen during MT SMS validity period, i.e. 24 hours after sending of MT. 3rd party can choose HTTP request type (POST or GET).

NOTE: All parameters are URL encoded.

Here is the list of available parameters for delivery reports:

ParameterDescription
mobile 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: mobile=41781234567
short_id Premium Short-ID on which MO message is sent.

Example: short_id=919
int_id Unique message ID on HORISEN’s side (returned in XML report during MT submission). Message ID is string with maximum length of 30 characters.
ext_id 3rd party's MT message id defined in ext_id parameter of MT message
status 1 – Delivered
2 – Undelivered
4 – Sent to operator
price Price of MT message

Example

In case of delivered MT HTTP GET request will be:

http://3rd.party.net/sms/dlr?mobile=41781234567&short_id=919&int_id=255513&ext_id=756ab34cf2&price=1.50&status=1

Delivery Report response

3rd party should reply with HTTP 200 and empty request body.

Appendices

Session Handling

Any keyword can be session based. The session is relevant only for MO messages. There are 3 stages in «session life»:

Starting Session

» Mobile user starts session by MO message containing keyword name.

Example:

Mobile user sends: test on 919 short ID.

Part of MO message parameters:

text=test&keyword=TEST%40919&session_id=342&session_status=C

Session running

» When session is started the following messages are part of the same session, mobile user doesn't need to send keyword name at the beginning of the message.

Example:

Mobile user sends: some text on 919 short ID.

Part of MO message parameters:

text=some%20text&keyword=TEST%40919&session_id=342&session_status=A

Session stopping

» Mobile user finishes the session by sending word «stop».

Example:

Mobile user sends: stop on 919 short ID.

Part of MO message parameters:

text=stop&keyword=TEST%40919&session_id=342&session_status=S

At the same time 3rd party can control session by MT messages (but only existing sessions). If session is running and 3rd party wants to stop it then MT message request could look like:

Part of MT message parameters:

text=goodbye&keyword=TEST%40919&session_id=342&session_status=S

ABO Services

ABO services are actually subscription based SMS services. The mobile user is subscribing on service by SMS, then 3rd party is sending content periodically with defined frequency until mobile user unsubscribe from service (by sending SMS or by contacting 3rd party or SMS provider).

The ABO service is usually passing through 3 stages: starting subscription, active subscription and stopping subscription.

Starting subscription

Starting subscription is initiated by mobile user with MO message in form: START SERVICE where SERVICE is keyword name which is redirected by premium transit to 3rd party.

The legal procedure for starting service is not the same in all countries; in Switzerland it is so called double opt-in. Whatever procedure is, it's handled by SMS provider (HORISEN) and when it is finished 3rd party is getting START SERVICE MO on his side.

After receiving START message, 3rd party is obliged to reply with MT message and to confirm that mobile user is subscribed on service, in this case 3rd party has to use START price code: price=0&price_code=START

If mobile user missed some syntax rules required to subscribe then MT message should contain regular price without price code (so, it is possible that reply on START MO is not creating valid subscription).

Active subscription

After successful subscription start, 3rd party can send MT push messages in intervals defined in service description; these are so called content messages. Content messages can be regularly charged.

Stopping subscription

The subscription can be stopped by two sides: by mobile user of by 3rd party.

Mobile user can stop subscription by sending: STOP SERVICE or by few other variations of STOP command. In all cases, 3rd party will get MO message in form: service STOP .

When 3rd party receives STOP MO he is obliged to reply with confirmation MT where he informs mobile user that his subscription is stopped and this MT has to have STOP price code: price=0&price_code=STOP

The other way to stop subscription is by 3rd party side. In this case, 3rd party can send MT push message with information that subscription is stopped but it is very important to use STOP price code

Complete ABO procedure can be explained in two sentences: ABO status of the user is controlled by 3rd party by using START and STOP price codes. START price code is allowed only like a confirmation for subscription start; STOP price code is used to cancel subscription and it has to be reply to STOP MO request or it could be sent by 3rd party at any moment.

Cookbook

In order to receive the MO messages, customer needs to provide to HORISEN the following:

  • Server: http://85.28.24.170:6825/
  • Protocol: HTTP POST; The URL that should be called should looks like: http://85.28.24.170/index.php:6825?short_id=919&from=417877887788&text=messagetext&provider=SWISSCOM&keyword=TEST@919&message_id=453248language=DE&Session_id=23543&session_status=A
  • Every submission (from HORISEN to customer or from customer to HORISEN) must be confirmed by XML status report. The text content is encode by ISO-8859-1 codepage, and characters which is not supported by mobile phones will be replaced with space character. It should look like: 
    <?xml version="1.0"?>
<report>
    <status>success</status>
</report>
  • HORISEN will provide static IP address the MO messages coming from (for security reasons).
  • In order to receive the MT messages from customer, HORISEN will provide:
    • Server: http://25.24.54.170:3325/
    • Protocol: HTTP POST;
    • Customer also has to provide static IP address the MT requests will coming from.
    • The URL should look like: http://horisen_server/index.php:3325?account=29&username=customer&password=customer&short_id=919&to=417877887788&text=messagetext&provider= SWISSCOM&keyword=TEST@919&price=60
  • The reply from HORISEN’s side is very similar to already described form. Beside status tag we will always offer some additional information. 
    <?xml version="1.0"?>
<report>
    <status>success</status>
    <msg_id>65343</msg_id>
</report>
  • A response in the case of rejected message should look like: 
    <?xml version="1.0"?>
<report>
    <status>error</status>
    <error_code>X</error_code>
    <error_desc>The description of the error</error_desc>
</report>