null

SMS Gateway

Handbook for CP

May 2009

Product Name: SMS Gateway Document Title: SMS Gateway Handbook for CP

Proprietary and Confidential Page i of 46 SMS Gateway Handbook for CP.doc

This document contains commercially sensitive information.

Reproduction is prohibited.

Confidentiality statement:

All information contained in this document is confidential and proprietary to XL, and intended only for

the addressee to whom this copy is addressed. The recipient shall not copy, distribute, disclose, or

use the information contained in it for any purpose other than that for which this document has been

made available or permit anyone else to do the same, without the express written permission of XL.

Amendment Record

Version Date Change

20090504 May 2009 Reflects SMSGW changes starting June 2009

20090508 May 2009 Updated section 4.1, 5.1.1, 6.1.1 (encrypted MSISDN)


Proprietary and Confidential Page ii of 46 SMS Gateway Handbook for CP.doc

Table of Contents

Table of Contents ...................................................................................................................ii

Table of Figures .................................................................................................................... iv

1 Introduction ..................................................................................................................... 1

2 Service Management ...................................................................................................... 2

2.1 What Is a Service? .................................................................................................................. 2

2.2 Using the Service Management Tool ...................................................................................... 4

2.2.1 Adding New Service ............................................................................................................ 5

2.2.2 Editing Keyword .................................................................................................................. 8

3 Changes to MO and MT ............................................................................................... 10

3.1 Subscription Will be Recorded .............................................................................................. 10

3.2 source_addr of MO and dest_addr of MT Will be Encrypted ................................................ 10

3.2.1 Encrypted MSISDN Helper Tool ....................................................................................... 10

3.3 Optional Parameters ............................................................................................................. 12

3.3.1 TX _ID in MO and MT ....................................................................................................... 12

3.3.2 Shortname in MT ............................................................................................................... 12

3.3.3 Content-Type inside MT for Quiz Service ......................................................................... 12

3.4 Additional Rules .................................................................................................................... 12

3.4.1 MT for Push Service Will be Limited ................................................................................. 12

3.4.2 No Next Question before Answer ...................................................................................... 12

3.5 Difference between CP’s Subscription Records and SMSGW’s .......................................... 12

4 SMPP Pipeline.............................................................................................................. 14

4.1 New Parameters ................................................................................................................... 15

4.2 MT Charging.......................................................................................................................... 16

4.2.1 Directly Connected to MT Charging Unit .......................................................................... 17

4.2.2 Status ID of Submit SM Response.................................................................................... 17

4.2.3 Delivery Report .................................................................................................................. 19


Proprietary and Confidential Page iii of 46 SMS Gateway Handbook for CP.doc

5 iSMS Protocol ............................................................................................................... 23

5.1 iSMS Protocol Description .................................................................................................... 23

5.1.1 MO SMS: HTTP Request from SMSGW to Content ......................................................... 23

5.1.2 MO SMS: HTTP Response from Content to SMSGW ...................................................... 25

5.1.3 Delivery Report: HTTP GET Request from SMSGW to Content ...................................... 26

5.2 Delivery Report: HTTP Response from Content to SMSGW. ............................................... 27

5.3 iSML Description ................................................................................................................... 28

5.3.1 Interactive Session ............................................................................................................ 28

5.4 iSML DTD .............................................................................................................................. 30

6 Push Protocol ............................................................................................................... 33

6.1 Push Protocol Description ..................................................................................................... 34

6.1.1 MT SMS: HTTP Request from Content to SMSGW ......................................................... 34

6.1.2 MT SMS: HTTP Response from SMSGW to Content....................................................... 37

6.1.3 Delivery Report .................................................................................................................. 45


Proprietary and Confidential Page iv of 46 SMS Gateway Handbook for CP.doc

Table of Figures

Figure 2.1: Service is combination between SDC and keyword ............................................................. 2

Figure 2.2: Keyword rules ....................................................................................................................... 3

Figure 2.3: Service Management tool login screen ................................................................................ 4

Figure 2.4: Failed to log into the tool ....................................................................................................... 5

Figure 2.5: Service lists page .................................................................................................................. 5

Figure 2.6: Create new service ............................................................................................................... 6

Figure 2.7: Successfully proposed service ............................................................................................. 7

Figure 2.8: Required fields not filled ....................................................................................................... 7

Figure 2.9: Find service to modify keyword ............................................................................................ 8

Figure 2.10: Modify keyword ................................................................................................................... 9

Figure 2.11: Successfully modified keyword ........................................................................................... 9

Figure 3.1: Encrypted MSISDN helper page ......................................................................................... 10

Figure 3.2: Encrypted MSISDN shown ................................................................................................. 11

Figure 3.3: Encrypted MSISDN limit reached ....................................................................................... 11

Figure 4.1: Connected to MT Charging Unit ......................................................................................... 17

Figure 5.1: SMSGW and Content application Interaction ..................................................................... 23

Figure 5.2: HTTP Request from SMSGW to Content ........................................................................... 24

Figure 5.3: HTTP Response from Content to SMSGW ........................................................................ 25

Figure 5.4: HTTP GET Request from SMSGW to Content ................................................................... 26

Figure 5.5: HTTP Response from Content to SMSGW ........................................................................ 27

Figure 5.6: Interactive Session.............................................................................................................. 29

Figure 6.1: Push SMS: HTTP POST/GET� HTTP Response � MT SMS ......................................... 33

Figure 6.2: Delivery Report Transaction ............................................................................................... 33

Figure 6.3: MT SMS: HTTP Request from Content to SMSGW ........................................................... 34

Figure 6.4: MT SMS: HTTP Response from SMSGW to Content ........................................................ 38


Proprietary and Confidential Page v of 46 SMS Gateway Handbook for CP.doc

Figure 6.5: MT Charging is successful .................................................................................................. 39

Figure 6.6: MT Charging is not successful ............................................................................................ 39

Figure 6.7: Delivery Report: HTTP GET Request from SMSGW to Content ........................................ 45

Figure 6.8: Delivery Report: HTTP Response from Content to SMSGW ............................................. 46


Proprietary and Confidential Page 1 of 46 SMS Gateway Handbook for CP.doc

1 Introduction

Before June 2009, SMS Gateway (SMSGW) managed traffic between SMSC and CP on the transport

level. Starting from June 2009, SMSGW manages the transport level and more things from the

application level. This is quite a big change. Therefore this document is provided to detail the changes

and also serves to supersede any previous documents on SMSGW and CP interaction.

Chapter 1 – 3 will explain the newest changes for SMSGW.

Chapter 4- 6 will explain about the technical detail for each protocol.



2 Service Management

2.1 What Is a Service?

CP needs to input its services into SMSGW. A service is a combination between Short Destination

Code (SDC) and a keyword.

Figure 2.1: Service is combination between SDC and keyword

Use the tool provided with SMSGW to input your services. The tool is a web based application. Ask

XL’s system administrator for the URL of the tool.

A service has a type. The type can be one of the following:

1. Push

This type of service requires subscription. Usually daily Mobile Terminated (MT) SMS will be sent

to the subscriber.



2. Pull

This type of service requires no subscription. MT SMS will be sent only on request from Mobile

Originated (MO) SMS.

3. Quiz

This type of service requires subscription and the rules for this service will be explained in section

[].

Since services are differentiated by the keywords, the following rules apply:

• On one SDC, if a keyword has been used for Push service, it can still be used for Pull service.

• However, if the keyword is already used for service with type Quiz, the keyword can no longer be

used for Push and Pull services.

The following figure shows the rule above:

Figure 2.2: Keyword rules



2.2 Using the Service Management Tool

First, ask for an account to the service management tool from your Account Manager (AM). After you

get the account, use it to login to the tool. The following figure shows the login screen:

Figure 2.3: Service Management tool login screen

Check your username and password if you get “Invalid username and password” message. Password

is case sensitive.



Figure 2.4: Failed to log into the tool

2.2.1 Adding New Service

Click on Service Management menu to list your services. There is a filter where you can choose to

view all services, or only services with: ACTIVE, REJECTED, and PROPOSED status.

Figure 2.5: Service lists page



Click on the Add Service button to add new service. The following screen will show:

Figure 2.6: Create new service

• Shortname is used to tell which service relates to the MT. If you specify the same shortname

for more than one service, the tool will notify the error.

• Select the most appropriate category for your service.

• Select the type of your service as explained in section 2.1.

• Select the SDC for the service.

• Select the channel for the service. You should create one service for each channel. For

example: if your service runs on SMS and WAP, you should create one service for SMS and

another WAP.

• Put a checkmark on the Set Expired Date if your service is set to expire on certain date.

Otherwise, for long running services, you don’t have to check the box.

• Type a short description for the service.

• Type in the keywords. At least 1 keyword has to be provided. Separate the keywords using

comma

• After you finish, click on the Propose button.

• A notification will be sent to the AM.

• The proposed service should show up in the service list with the status column showing

“Proposed”.



• Check back to find out whether the proposed service is accepted or rejected by the AM. You

can tell by watching the status of your service.

Figure 2.7: Successfully proposed service

If you leave required fields unfilled, you will get error messages like shown below. Please fill all

required fields.

Figure 2.8: Required fields not filled



2.2.2 Editing Keyword

You can edit the keywords for your service before or after your service becomes ACTIVE. When your

service is still PROPOSED, editing keywords just means sending newer notifications to your AM.

However, if your service is ACTIVE, be very careful when you want to edit keywords.

Please make sure your AM approves the keyword changes for ACTIVE services as soon as possible.

This is so because when ACTIVE service undergoes keyword editing, the service will change status

to PROPOSED. You need to make sure the AM approves this immediately to ensure the well running

of your service.

The following is the procedure to edit keywords:

1. Login to the tool.

2. Bring up the service management page by clicking Service Management menu.

3. Find the service which keywords need to be edited. Click the link on service name.

Figure 2.9: Find service to modify keyword

4. Modify the keyword as necessary. After you have finished, click the Modify Keyword button.



Figure 2.10: Modify keyword

5. Your service will become PROPOSED. This is why you need your AM to approve as soon as

possible so it can be ACTIVE.

Figure 2.11: Successfully modified keyword



3 Changes to MO and MT

3.1 Subscription Will be Recorded

Subscription for SMS services is controlled by the customer. Customer sends MO with REG as the

first word to subscribe. On the contrary, he sends MO with UNREG as the first word to unsubscribe.

Unlike the previous version of SMSGW, the current one will record the REG and UNREG.

3.2 source_addr of MO and dest_addr of MT Will be Encrypted

CP will no longer receive clear MSISDN from MO and it can no longer submit MT with clear MSISDN.

3.2.1 Encrypted MSISDN Helper Tool

In case of complaint from customer, CP will face a problem handling the complaint since it no longer

has the clear MSISDN in its database. For this situation a tool is provided.

The tool is very easy to use; just follow these simple steps after you ask the URL from XL’s system

administrator:

1. Login to the tool.

2. Click the Encrypted MSISDN Helper menu.

Figure 3.1: Encrypted MSISDN helper page



3. Type the clear MSISDN.

4. Input the CAPTCHA text. Type correct letters or digits from distorted image that appears on the

CAPTCHA screen.

5. Click on the Encrypt button.

6. It will show the encrypted MSISDN.

Figure 3.2: Encrypted MSISDN shown

CP is given daily usage limit of this tool. Please do not abuse.

In case the limit is reached, CP cannot perform anymore encryption, as the figure below shows:

Figure 3.3: Encrypted MSISDN limit reached



3.3 Optional Parameters

3.3.1 TX _ID in MO and MT

Whenever CP receives an MO, a token called TX_ID will be embedded in the optional parameter.

Simply copy the value and embed the same token in MT.

3.3.2 Shortname in MT

As previously mentioned in page 6, SMSGW has to know which service relates to the MT. Just embed

shortname inside the optional parameter.

3.3.3 Content-Type inside MT for Quiz Service

MT for Quiz service must include Content-Type inside the optional parameter. There are 2 values:

• INFO

• QUESTION

3.4 Additional Rules

3.4.1 MT for Push Service Will be Limited

SMSGW keeps track of the number of MT submitted by CP for its Push services. Please do not

submit more MT than specified in the Product Brief.

3.4.2 No Next Question before Answer

For Quiz services, CP is allowed to send 1 INFO and 1 QUESTION per day. If the subscriber has not

answered the QUESTION for that day, CP will not be able to send more QUESTIONs. However, CP

is welcome to send more QUESTIONs if the subscriber answers.

3.5 Difference between CP’s Subscription Records an d SMSGW’s

There will be time when CP’s subscription records differ from SMSGW’s. The possible causes are:



• Sub sends UNSUB, STOP, OFF

If SMSGW receives MO with either one of: UNSUB, STOP, or OFF; SMSGW will not pass

the MO to CP and it will conduct auto unsubscribe of the MSISDN from all services in all

SDC.

• Sub sends UNREG (remove from 1 SDC)

If SMSGW receives MO with only UNREG, SMSGW will not pass the MO to CP and it will

conduct auto unsubscribe of the MSISDN from all services on that SDC.

• Sub has not answered the QUIZ (more than 6 times)

When subscriber of QUIZ service does not answer 5 consecutive QUESTIONs, SMSGW

will conduct auto unsubscribe of the MSISDN from that QUIZ service on the 6th

QUESTION. Thus, please remove the MSISDN from your (CP) subscription record if you

receive MAX UNANSWERED QUESTIONs ERROR.

• MSISDN is obsolete

SMSGW will remove all subscription of an MSISDN if the network tells SMSGW that the

status of MSISDN is DEACT.



4 SMPP Pipeline

If your content is registered as an SMPP Pipeline application in the gateway, please read this section.

Ask your contact person at Excelcomindo to find out what your application is registered as.

Short Message Peer to Peer Protocol (SMPPP) is an open message-transfer protocol that enables

short message entities (SMEs) outside the mobile network to interface with SMSGW. SMPP is based

on the exchange of request and response protocol data units (PDUs) between your Content

Application and the SMS Gateway over an underlying TCP/IP or X.25 network connection.

The exchange of messages between your Content Application and SMSGW via SMPP may be

categorized under three distinct groups of transactions as follows:

• Messages sent from your Content Application (Transmitter) to SMS Site Server

• Messages sent from SMS Site Server to your Content Application (Receiver)

• Messages sent from your Content Application (Transceiver) to SMS Site Server and

messages sent from SMS Site Server to your Content Application (Transceiver)

An SMPP session between an SMSGW and your Content Application is initiated by the Content

Application first establishing a network connection with the SMS Site Server and then issuing an

SMPP Bind request to open an SMPP session. Your Content Application wishing to submit and

receive messages is required to establish two network connections (TCP/IP or X.25) and two SMPP

sessions (Transmitter and Receiver). Alternatively, in this version of the protocol, you may establish

an SMPP Transceiver session over a single network connection. During an SMPP session, you may

issue a series of requests to an SMSGW and shall receive the appropriate responses to each

request, from SMSGW. Likewise, you may issue SMPP requests to you, which must respond

accordingly.

The SMPPP session may be defined in terms of the following possible states:

• OPEN

Your content application has established a network connection to the SMSGW but has not yet

issued a bind request.

• BOUND_TX

A connected Content Application has requested to bind a content application transmitter (by

issuing a bind_transmitter PDU) and has received a response from the SMSGW authorizing its

bind request.



• BOUND_RX

A connected content application has requested to bind as a content application receiver (by

issuing a bind_receiver PDU) and has received a response from the SMSGW authorizing its bind

request.

• CLOSED (Unbound and Disconnected)

Your content application has unbound from the SMSGW and has closed the network connection.

The SMSGW may also unbind from the ESME.

4.1 New Parameters

Parameter Name Type MO/MT Description

5120 Shortname String MT Mandatory for all

service. Tells

SMSGW which

service this MT

relates to.

5121 TX_ID Integer MO and MT Mandatory for all.

5123 Content -Type String MT Mandatory for Quiz

service. Tells

SMSGW whether this

is INFO or

QUESTION.

Example PDU (in Hex):

1. Shortname = excelcom



The value for length (pictured above inside the third and fourth box from the left) must be the

same as the length of the string. In this example “excelcom” length = 8 characters, that’s why the

value in length field is 00 08.

2. Content-Type = question

3. Content-Type = info

4. TX_ID

The length is always 00 04.

4.2 MT Charging

This section applies only when your content uses MT charging



4.2.1 Directly Connected to MT Charging Unit

When you’re connected directly to the MT Charging Unit, you will know that your MT SMS is

successfully charged to the subscriber as soon as you receive a positive SUBMIT SM Response from

the unit regardless of whether the subscriber has received the SMS on their mobile.

• MT charging successful

• MT charging unsuccessful

Figure 4.1: Connected to MT Charging Unit

If you receive a negative SUBMIT SM Response (status NOT EQUAL 0), you know that the MT

charging does not succeed. Specifically, if you receive status = ESME_RSUBMITFAIL (0x00000045),

you know that the subscriber has no sufficient balance and MT charging does not succeed In this

case you will mark in your record that the particular MT SMS is not chargeable and you may optionally

retry (subject to your agreement with Excelcomindo). You can retrieve the status of SUBMIT SM

Response by looking to column command status of packet SUBMIT_SM_RESP, please see the

status ID of Submit SM Response.

4.2.2 Status ID of Submit SM Response

Submit SM response from SMSGW will contain the status ID of the MT. There are 3 kind of status ID:

1. Status 0: MT SMS has been submitted to MT Charging successfully

2. Internal error code, the error code from internal SMSGW



Error Code Description Able to Retry / No Retry

1000 Invalid command ID Retry

1001 Internal Error Retry

1002 Internal Maximum Queue

Exceeded

Retry

1003 No SMSSS Adapter Retry

1004 (reserved) Retry


1006 Invalid Application Password Retry.

1007 Content Not Active

(Blacklisted, Terminated,

Suspended)

Retry

1008 Content Not Registered Retry

1009 Push Quota Per Day

Exceeded

Retried after 24 hours

100A Push Quota Per Day

Exceeded

Retry

100B Content Whitelisted (Testing

mode)

Retry.

100C Incomplete Push Request

Parameters

Retried with the valid

parameter

100d Invalid SMS Data To Send Retry with the data fixed

1024 SMS Site Server achieve

timeout waiting ACK from

Billing MT

After receive this status code,

if partner application still

required to sent short message

(i.e. short message for

notification) , MUST retry using

Do not Retry




SDC that known as Zero MT

Charge . MT charge = Rp 0

1025 Queuing occur SMS Site

Server.

Application / ESME able to

retry since the short message

had not been sent to Billing

Gateway / MMX

Retry

1026 Problem occur on connection

between SMS Site Server and

Billing Gateway / MMX




Gateway / MMX

Retry

1027 Subscriber not found No Retry

1028 Number is deactivated No Retry

1030 Service terminated No Retry

1031 Service not found No Retry

1032 Invalid TX Id No Retry

1033 Push limit exceeded No Retry

1034 Max unanswered question

reached

No Retry

4.2.3 Delivery Report

4.2.3.1 Delivery Report Format

field Size

(octets) Type Description



field Size


id 10 C-Octet String

(Decimal)

The message ID allocated to the message by the

SMSC when originally submitted.

sub 3 C-Octet String

(Decimal)

Number of short messages originally submitted.

This is only relevant when the original message

was submitted to a distribution list. The value is

padded with leading zeros if necessary.

dlvrd

3 C-Octet

Fixed Length

String

(Decimal)

Number of short messages delivered. This is

only relevant where the original message

was submitted to a distribution list. The

value is padded with leading zeros if

necessary.

submit

date

10 C-Octet Fixed

Length String

The time and date at which the short message

was submitted. In the case of a message which

has been replaced, this is the date that the

original message was replaced. The format is as

follows:

YYMMDDhhmm where:

YY = last two digits of the year (00-99)

MM = month (01-12)

DD = day (01-31)

hh = hour (00-23)

mm = minute (00-59)

done

date

10 C-Octet Fixed

Length String

The time and date at which the short message

reached its final state. The format is the same as

for the submit date.

stat

7 C-Octet Fixed

Length String

The final status of the message. For settings for

this field see Table B-2.

err 3 C-Octet Fixed

Length String

Where appropriate this may hold a Network

specific error code or an SMSC error code for the



field Size


attempted delivery of the message. These errors

are Network or SMSC specific and are not

included here.

text 20 Octet String The first 20 characters of the short message.

4.2.3.2 Example Delivery Report

Message State Final Message

States Description

DELIVERED DELIVRD Message is delivered to destination

EXPIRED EXPIRED Message validity period has expired.

DELETED DELETED Message has been deleted.

UNDELIVERABLE UNDELIV Message is undeliverable

ACCEPTED

ACCEPTD

Message is in accepted state (i.e. has

been manually read on behalf of the

subscriber by customer service)

UNKNOWN UNKNOWN Message is in invalid state

REJECTED REJECTD Message is in a rejected state

Here are the items that you must pay attention to the following important notes in handling your

transactions: please see SMPP Specification for more details.

1. Please use timeout value 60 seconds for waiting SUBMIT SM responses from SMS Site Server. If

after 60 seconds at maximum your Content Application hasn't received SUBMIT SM responses,

then the transaction can be considered as failed transaction.

2. SUBMIT SM responses tell you everything you need to know about the charging state of your

transactions.



3. You CAN ONLY perform retries on SUBMIT SM responses with status id other than 0. However,

please also notify that it MUST NOT break XL rules about which error code can be retried and

which error code cannot. Please see Appendix, for the list of those special error codes and the

treatment CP should taken care based on them.

4. Therefore you MUST NEVER retry on receiving a negative Delivery Report.

5. You MUST NOT do retry for failed MT transaction due to timeout waiting SUBMIT_SM_RESP

from SMSGW.

6. By default, you will not receive a Delivery Report anymore, but you can ask to activate Delivery

Report. Even though Delivery Report has been requested, it would be the Delivery Report will not

be sent to you because as default, Delivery Report is disabled.

7. Your application must perform a graceful termination by sending the UNBIND.



5 iSMS Protocol

iSMS protocol is an HTTP-based protocol that enables the SMSGW to pass a mobile originating (MO)

SMS to a content application/service and get a response back from the content application that will be

sent back to the originating mobile as a mobile terminated (MT) SMS.

iSMS also includes a mechanism of passing a delivery report from SNSGW to a content application.

Diagram below describes the interaction between the SMSGW and content application.

Figure 5.1: SMSGW and Content application Interaction

The iSMS protocol defines:

• The HTTP POST request for MO SMSGW to content application

• The iSML (Interactive SMS Markup Language) that a content application must send back to

SMSGW in the HTTP response for MO SMS

5.1 iSMS Protocol Description

When a mobile sends an SMS that is received by SMSGW from the SMSC, SMSGW will decide

which content application the MO SMS belongs to and forward it to the correct one.

Here the explanation below about how the server passes the MO SMS to the content application and

how the content application should respond.

5.1.1 MO SMS: HTTP Request from SMSGW to Content

SMSGW passes the MO SMS to the chosen content application by sending an HTTP POST request

to the content application.

The following explains the details:



Figure 5.2: HTTP Request from SMSGW to Content

• Headers

Parameter Name Description

X-Source-Addr The MSISDN of the SMS sender. It will be in encrypted

format.

X-Dest-Addr The destination of the SMS, usually the short code i.e.

9090, 9554

X-Pull-Trx-Id Transaction ID Pull

• Request Parameters


_sc The content of the SMS, as a string of characters. If the

SMS is of UCS2, it will be converted to characters using

UCS2 encoding (UTF-16BE)

_tid The transaction ID (20 characters), uniquely identifying

this MO and MT SMS pair. This transaction ID is used

by SMSGW to send delivery report, if applicable.

Note that the HTTP request is sent to the URL registered for the content application.

There will be other header information passed as part of a complete HTTP request but they are not

significant as far as the iSMS protocol goes.



If you tap the TCP/IP traffic form the SMSGW to the content application, you will get something like

the following (let’s assume that the URL path of the content is /quiz.jsp):

POST/quiz.jsp HTTP/1.1

X-Source-Addr: 0697055743607

X-Dest-Addr: 1235

User-Agent: Jakarta Commons-HttpClient/2.0rc1

Content-Length: 39

Content-Type: application/x-www-form-urlencoded

_sc= TEMPO+A+tidak+manusiawi&_tid=610410BFFBED3E3B9FF7

5.1.2 MO SMS: HTTP Response from Content to SMSGW

When a content application receives the HTTP request from SMSGW, it must respond with HTTP

status code 200 and carry valid iSML document in the response body.

Figure 5.3: HTTP Response from Content to SMSGW

Content type of the response must be text/xml.

SMSGW will parse the iSML document and if applicable, send an MT SMS to originating mobile

according to the instruction in the iSML document.

HTTP response headers other than the content type are not significant as far as the iSMS protocol

goes.

Example of a complete HTTP response:

HTTP/1.1 200 OK

Content-Type: text/xml

Content-Length: 139

Date: Wed, 05 Nov 2002 14:38:01 GMT

Server: Apache Coyote/1.0



<?xml version=”1.0”>

<isml>

<card id=”thanks” title=”Thanks”>

<p> Terima kasih atas opini anda.</p>

</card>

</isml>

5.1.3 Delivery Report: HTTP GET Request from SMSGW to Content

When SMSGW receives delivery report from the SMSC, it will forward the report to the corresponding

content application by sending an HTTP GET request to the content application.

The following explains the details:

Figure 5.4: HTTP GET Request from SMSGW to Content



Mandatory Parameters

_tid The transaction ID to be used by content applications to

find the original SMS transaction

status_id The status of the MT SMS as follows:

101 = Undeliverable

102 = Delivered



dtdone The time and date the MT SMS reached its final state, in

YYYYMMDDHHMISS format where

YYYY = year (4 digit number)

MM = date as a 2 digit number (01-12)

DD = date as a 2 digit number (01-31)

HH = hour (00-23)

MI = minute (00-59)

SS = second (00-59)

Optional Parameters

smpp_status_code The error code from the SMPP server (see SMPP

specification)

An example of a delivery report is:

POST/delivery.jsp HTTP/1.1

User-Agent: Jakarta Commons-HttpClient/2.0rc1

Content-Length: 61

Content-Type: application/x-www-form-urlencoded

_tid=610410BFFBED3E3B9FF7&status_id=102&dtdone=20031105214333

5.2 Delivery Report: HTTP Response from Content to SMSGW.

Upon receiving the HTTP GET request from SMSGW, a content application must respond with HTTP

status code 200. SMSGW will ignore the HTTP response body.

Figure 5.5: HTTP Response from Content to SMSGW



If a content application responds with HTTP status code other than 200, SMSGW will ignore the

response.

5.3 iSML Description

iSML is an XML document that defines the SMS response from a content application.

Example of a simple iSML response:

<?xml version=”1.0”?>

<isml>

<card id=”hello”>

<p>Hello World!</p>

</card>

<isml>

When SMSGW receives the above iSML from a content application, it will send an MT SMS back to

the originating mobile containing the text “Hello World!”

Example of an empty iSML response:


</isml>

When SMSGW receives the above iSML from a content application, it will not send any MT SMS back

to originating mobile.

5.3.1 Interactive Session

The previous iSML examples are simple, i.e. a mobile sends an MO SMS and the content sends back

a reply MT SMS and it stops there.

What if you want to have a session (a state) into the interactivity? For example, suppose you want to

have an interactive question and answer survey application with keyword “XX” as follows:



Figure 5.6: Interactive Session

5.3.1.1 Interactive SMS Session Example

User sends an SMS “XX SURVEY”, which will be routed to the survey content service.

The content service will send back with an SMS prompting the user to enter his name. When the

system receives the name, it will send back the first survey question and so forth. This kind of survey

application can be implemented with the following iSML document:

First document:


<isml>

<card id=”hello”>

<menu showchoice=”off”>

<prompt>Halo, terima kasih atas ketersediaan anda ikut survey

Silahkan ketik nama anda.<prompt>

<nomatch><goto next=”/savename.jsp”/></nomatch>

</menu>

</card>

</isml>

In the above iSML example, whatever response the user sends will cause SMSGW to issue an HTTP

POST to URL path /savename.jsp (the same host and port as the current context), passing the usual

header and request parameters (see section 3.1.1 MO SMS: HTTP Request from SMSGW to

Content).



Your application at /savename.jsp should process the SMS, which should contain the user name.

Then your application will produce the following second document (either by redirecting to another

URL or outputting it directly on the response).

Second document (after you process the user name in /savename.jsp in the above example):


<isml>

<card id=”survey”>

<menu showchoice=”off”>

<prompt><%=username%>, setujukan anda Abubakar Baasyir divonis 4 tahun sebagai

teroris? <prompt>

<choice next=”/setuju.jsp” token=”setuju”>SETUJU</choice>

<choice next=”/tidak.jsp” token=”tidak”>TIDAK</choice>

<nomatch><goto next=”/showhelp.jsp”/></nomatch>

</menu>

</card>

</isml>

This time the above document tells the SMSGW to send back an SMS to the user and present the two

options, i.e. SETUJU or TIDAK. When the user responds with an SMS “SETUJU”, the SMSGW knows

that it has to issue an HTTP POST request to the URL /setuju.jsp.

If the user responds with an SMS other than SETUJU or TIDAK (and assuming there is no other

application matching that answer keyword defined for the short code), SMSGW will issue an HTTP

POST request to URL /showhelp.jsp, as indicated by the no match element.

Note that in order to take advantage of this feature, the interactive session must be explicitly enabled

for your content application. Please contact the operator administrator.

5.4 iSML DTD

<!ENTITY % uri "CDATA">

<!ENTITY % coreattrs

"id ID #REQUIRED" >

<!ENTITY % text "#PCDATA" >

<!ELEMENT isml

(card+)+ >



<!ELEMENT card

( menu | p ) >

<!ATTLIST card

%coreattrs;

title CDATA #IMPLIED

display-only (yes|no)”no”

registered (yes|no)”no” >

<!ELEMENT menu

( prompt?,choice+, nomatch?) >

<!ATTLIST menu

showchoice (on|off) “off”

timeout CDATA #IMPLIED >

<!ELEMENT p

( %text; ) >

<!ELEMENT prompt

( %text; ) >

<!ELEMENT choice

( %text; ) >

<!ATTLIST choice

next %uri; #REQUIRED

token CDATA #REQUIRED >

<!ELEMENT nomatch

( goto ) >

<!ELEMENT goto EMPTY>

<!ATTLIST goto

next %uri; #REQUIRED >



<!ELEMENT timeout

( %text; ) >



6 Push Protocol

Push protocol is an HTTP-based protocol that enables content applications to send an SMS to an

MSISDN proactively and optionally receive its delivery report.

Below is a diagram that describes the interactions between the SMSGW and content application.

Figure 6.1: Push SMS: HTTP POST/GET� HTTP Response � MT SMS

Figure 6.2: Delivery Report Transaction

The Push protocol defines:

1. The HTTP POST/GET request for MT SMS from content applications to SMSGW.

2. The HTTP response XML from SMSGW to content applications, which acknowledges the MT

SMS transmission request.

3. The HTTP GET request for delivery report from SMSGW to content applications, if delivery

report option for the corresponding content application is enabled.

4. The HTTP response from content applications to SMSGW acknowledging the delivery report.



6.1 Push Protocol Description

6.1.1 MT SMS: HTTP Request from Content to SMSGW

A content application sends an MT SMS to an MSISDN by sending HTTP POST/GET request to

SMSGW”

Figure 6.3: MT SMS: HTTP Request from Content to SMSGW

There are 2 versions: Simple Text and Full Option.

6.1.1.1 Simple Text Version: Request Parameters


dest_addr The encrypted MSISDN to send MT SMS to.

app_id The content application ID, assigned by the operator

administrator

app_pwd The content application password, assigned by the

operator administrator

text The SMS text to send

short_name Short name service, a name used by CP to identify a

service to SMSGW

source_addr The SDC to send MT SMS to the headset (dest_addr).

tx_id Transaction ID



Simple text enables a content application to send an SMS text using the default alphabet with no

delivery report. If parameter “text” is longer than 160 characters, SMSGW will send 2 (two) or more

MT SMS that form a concatenated long SMS as according to GSM 03.40.

• Example:

http://202.152.224.18:10099/webpush/pushText.jsp?dest_addr=628176711016&app_id=2000006

6&app_pwd=testurl&text=Terima+kasih+anda+telah+berpartisipasi+dalam+poling+sms+kami&sh

ort_name=cndxx&source_addr=9999. This example shows the http request using the mandatory

parameters.

6.1.1.2 Full Option: Request Parameters



dest_addr The encrypted MSISDN to send MT SMS to.

app_id The content application ID, assigned by the operator

administrator

app_pwd The content application password, assigned by the

operator administrator

data The SMS data to send. If the data is of type binary or

UCS2, it must be encoded as a string of hex.

E,g, “45A06132”

short_name Short name service, a name used by CP to identify a

service to SMSGW

source_addr The SDC to send MT SMS to the headset (dest_addr).

tx_id Transaction ID (only for Pull reply)

Optional Parameters

udhi User Data Header indicator (“yes” or “no”)

Default is “no”.



alphabet_id The alphabet ID of “data” (“0” for default alphabet, “1”

for 8 bit data, “2” for UCS2 alphabet)

Default is “0”.

msg_class The message class, as defined in GSM 03.38 (valid

values are 0 – 3)

Default is “1”.

protocol_id The protocol ID, as defined in SMPP specification. It

must be encoded as a string representation of the byte

value in hex.

Default is “0”

registered Whether the content requests a Delivery Report (“yes” or

“no”)

Default is “no”.

pull_sp Pull special

content_type Content type parameter to differentiate whether an MT is

Info or Question.

Full option enables a content application to send an SMS data including binary data such as

ringtones, picture logos, WAP push, etc. Full option exposes the complete options for sending an

SMS.

If a content partner wants to send text SMS with delivery report enabled, then they should use this

feature.

• Example:

o http://202.152.224.18:10099/webpush/push.jsp?dest_addr=628176711016&app_id=2000

0066&app_pwd=testurl&data=0B0504C34FC0020003040202296A010186071103687474

703A2F2F7761702E646B0001&udhi=yes&alphabet_id=1

This example in the above shows the http request using the mandatory parameters. The

data that being sent is part of a ring tone binary that has been encoded into hexadecimal.

Maximum byte that can be sent in one sms is about 140 bytes, which when encoded into

hexadecimal are about 280 characters. If you split the ringtone into two or more parts,



then you must supply the udhi parameters (set it to yes), so that the ring tone can be

joined again after arrived in the user mobile phone. For sending binary data, you must

supply the alphabet_id parameter (set it to 1).

o http://202.152.224.18:10099/webpush/push.jsp?dest_addr=

20000066&app_pwd=testurl&data=0B0504C34FC0020003040202296A01018607110368

7474703A2F2F7761702E646B0001&registered=yes

This example in the above shows the http request using the mandatory parameters. The

data that being sent is part of a ring tone binary that has been encoded into hexadecimal

and that the content is requesting a Delivery Report. The CP must supply the address

where the delivery report is going to be sent.

o http://202.152.224.18:10099/webpush/push.jsp?dest_addr=628176711016&app_id=2000

0066&app_pwd=testurl&data=Terima+kasih+anda+telah+mengirim+sms+kuis+hari+ini&r

egistered=yes&msg_class=0

This example in the above shows when the content partner sent a flash sms (define by

msg_class parameter set to 0).

6.1.2 MT SMS: HTTP Response from SMSGW to Content

Upon receiving the HTTP request from a content application, SMSGW will respond back with HTTP

status code 200 and a push response XML in the HTTP response body.

Push response XML will be either of the following forms:

<?xml version="1.0"?>

<push-response>

<tid>the transaction id</tid>

<status-id>the status of the request</status-id>

</push-response>

or

<?xml version="1.0"?>

<push-response>

<status-id>the status of the request</status-id>

<message>the error message</message>



</push-response>

Content type of the response is text/xml

Element Name Description

tid The transaction ID that serves as the unique ID for the

request. This is the ID that will be used by SMS Site

Server to relay the delivery report to content.

This is a 20 characters length string.

status-id The status of the request.

0 = OK

See details Internal Error Codes list

message The error message

Content applications must parse the returned XML

Figure 6.4: MT SMS: HTTP Response from SMSGW to Content

When MT SMS is successfully charged to the subscriber as soon as you receive a positive HTTP

Response from the SMS Site Server regardless of whether the subscriber has received the SMS on

their mobile.

If you receive a HTTP Response (status EQUAL 0), the MT charging succeed.



Figure 6.5: MT Charging is successful

If you receive a HTTP Response (status NOT EQUAL 0), you may know that the MT charging does

not succeed.

Figure 6.6: MT Charging is not successful

6.1.2.1 Status ID of HTTP Responses

HTTP responses from SMSGW will contain the status ID of the MT. There are 3 kind of status ID:

1. Status 0: MT SMS has been submitted to MT Charging successfully

2. Internal Error Codes: The error codes from internal SMSGW


1000 Invalid command ID Retry

1001 Internal Error Retry

1002 Internal Maximum Queue

Exceeded

Retry

1003 No SMSSS Adapter Retry






1006 Invalid Application Password Retry.

1007 Content Not Active

(Blacklisted, Terminated,

Suspended)

Retry

1008 Content Not Registered Retry

1009 Push Quota Per Day

Exceeded

Retried after 24 hours

100A Push Quota Per Day

Exceeded

Retry

100B Content Whitelisted (Testing

mode)

Retry.

100C Incomplete Push Request

Parameters

Retried with the valid

parameter

100d Invalid SMS Data To Send Retry with the data fixed

1024 SMS Site Server achieve

timeout waiting ACK from

Billing MT

After receive this status code,

if partner application still

required to sent short message

(i.e. short message for

notification) , MUST retry using

SDC that known as Zero MT

Charge . MT charge = Rp 0

Do not Retry

1025 Queuing occur SMS Site

Server.




Gateway / MMX

Retry




1026 Problem occur on connection

between SMS Site Server and

Billing Gateway / MMX




Gateway / MMX

Retry

1027 Subscriber not found No Retry

1028 Number is deactivated No Retry

1030 Service terminated No Retry

1031 Service not found No Retry

1032 Invalid TX Id No Retry

1033 Push limit exceeded No Retry

1034 Max unanswered question

reached

No Retry

3. External Error Codes.

a. Existing error code triggered by SMSC

Error Code

Status Description Error Handling

Hexa Dec

0x500 1280 Rejected Insufficient Balance

Do not send same content to

this MSISDN and do not send

other content in 24 hours to

this MSISDN

0x502 1282 Rejected Param Sytem Error

Only able to retry after 24

hours to same MSISDN/

Destination

Should not sent further



Error Code

Status Description Error Handling Hexa Dec

content during 24 hours to

same MSISDN/Destination

0x503 1283 Rejected FDA System Error

Same content not be retried

and should not be sent further

content during 24 hours* to

same MSISDN

0x0FE 254 Rejected Delivery Failure


his MSISDN

0x011 11 Rejected

MSISDN Invalid

In case :

MSISDN is not XL

MSISDN or MSISDN

not in White List while

application still in

Testing stage

Delete this MSISDN from your

database start from now

0x002 2

Expired /

Undelivered

GSM error code-

Undefined User




this MSISDN

0x001 1

Expired /

Undelivered

GSM error code-

Unknown User




this MSISDN

0x018 24

Expired /

Undelivered

GSM error code-

Switch off station




this MSISDN

0x004 4

expired /

rejected /

undelivered

GSM error code-

teleservice not

supported






Error Code

Status Description Error Handling Hexa Dec

this MSISDN

0xFF 255 Rejected Unknown Error




this MSISDN

0x12 69 Rejected SUBMIT_SM failed




this MSISDN

b. Aggregating this error code into one general error code (Declined – Other)

Error Code


Hexa Dec

0x501 1281 Rejected

MSISDN

Invalid

Delete it and not be

retried and should not be

sent further content

during 24 hours to same

MSISDN

0X502

(Declined - Other)

1282 in Decimal 0x504 1284 Rejected

Internal

System Error

Same content not be



during 24 hours* to

same MSISDN

0x504 1285

Not

Authorized

Same content not be



during 24 hours* to

same MSISDN



Error Code


Hexa Dec

0x504 1286

Service

Barred

Same content not be



during 24 hours* to

same MSISDN

0x504 1287

Declined / No

Reserved

balance

Same content not be



during 24 hours* to

same MSISDN

0x515 1301 Rejected

MSISDN

Suspended

Not be retried and

should not be sent

further content during 24

hours* to same MSISDN

0x516 1302 Rejected

MSISDN

Terminated

Delete it and not be



during 24 hours to same

MSISDN

0x508 1288 Rejected

Balance

expired

Only Able to retry after

24 hours to same

MSISDN/ Destination

Should not send further

content during 24 hours

to same MSISDN/

Destination



6.1.3 Delivery Report

1. As default, delivery report will be disabled for all you, but you can ask to activate delivery

report. Even though delivery report has been requested, it would be the delivery Report will

not be sent to you because as default, Delivery Report is disabled.

2. Please use http connection timeout value 60 seconds for waiting HTTP Response from SMS

Site Server. If after 60 seconds at maximum your Content Application hasn't received the

response, then the transaction can be considered as failed transaction.

3. You CAN ONLY perform retries on HTTP responses with status id other than 0. However,

please also notify that it MUST NOT break XL rules about which error code can be retried and

which error code cannot. Please see enclosure Table 1, for the list of those special error

codes and the treatment CP should taken care based on them.

4. Therefore you MUST NEVER retry on receiving a negative Delivery Report.

5. You MUST NOT do retry for failed PUSH transaction due to timeout waiting HTTP response

from SMSGW.

6.1.3.1 Delivery Report: HTTP GET Request from SMSGW to Content

When SMSGW receives delivery report from the SMSC, if the delivery report option for the

corresponding content provider is enabled, then SMSGW will forward the report to the content

provider by sending an HTTP GET request to the content application with the following details:

Figure 6.7: Delivery Report: HTTP GET Request from SMSGW to Content






_tid The transaction ID to be used by content applications to

find the original SMS transaction

status_id The status of the MT SMS as follows:

101 = Undeliverable

102 = Delivered

dtdone The time and date the MT SMS reached its final state

Optional Parameters

smpp_status_code The error code from the SMPP server (see SMPP

specification)

6.1.3.2 Delivery Report: HTTP Response from Content to SMSGW

Upon receiving the HTTP GET request for delivery report form SMSGW, a content application must

respond with HTTP status code 200. SMSGW will ignore the HTTP response body.

Figure 6.8: Delivery Report: HTTP Response from Content to SMSGW

If a content application responds with HTTP status code other than 200, SMSGW will ignore the

response.

null

Documents

mo sms

addr of mt

document title

new service

mt charging unit

http response

addr of mo

quiz service