Premium Transit API

1. 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.

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

2. Technical Requirements

1. In order to receive the MO messages, you 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 you, HORISEN will provide:

   1. Server: http://<HORISEN_host_ip>:<port>
   2. Protocol: HTTP POST;
      You have to provide static IP address that the MT requests will coming from.

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

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

2.1 Parameters for Receiving MO Messages

The following parameters are available:

Parameter	Mandatory	Description
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

2.2 Mandatory Parameters for Sending MT Messages

The following parameters are required:

Parameter	Mandatory	Description
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

2.3 Optional Parameters for Sending MT Messages

The following parameters are optional:

Parameter	Mandatory	Description
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

2.4 XML Submission Response

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

2.5 Reply of 3rd party on MO request sent by HORISEN

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

The reply which has to be provided by you is:

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

2.6 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_code	error_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.

3. 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 the mobile operator. This request can happen during MT SMS validity period, i.e. 24 hours after sending of MT. You can choose HTTP request type (POST or GET).

Here is the list of available parameters for delivery reports:

Parameter	Description
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

3.1 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

3.2 Delivery Report response

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

4. Appendices

4.1 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 is 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

Stopping Session

» 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

You can control the session by sending MT messages (but only existing sessions). If session is running and you want 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

4.2 ABO Services

ABO services are actually subscription based SMS services. The mobile user is subscribing on service by SMS, then you are sending content periodically with defined frequency until the mobile user unsubscribe from the 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 to the 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 to 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.

5. 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 be 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>