Null

SMS Gateway
Handbook for CP
May 2009
Product Name: SMS Gateway
Document Title: SMS Gateway Handbook for CP
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 i 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 ii of 46

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 iii of 46

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 iv of 46

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 v of 46

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.
Proprietary and Confidential Page 1 of 46

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 and 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
th
will conduct auto unsubscribe of the MSISDN from that QUIZ service on the 6
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 Retry

Exceeded
1003 No SMSSS Adapter Retry
1004 (reserved) Retry
1006 Invalid Application Password Retry.
1007 Content Not Active Retry

(Blacklisted, Terminated,
Suspended)
1008 Content Not Registered Retry
1009 Push Quota Per Day Retried after 24 hours

Exceeded
100A Push Quota Per Day Retry

Exceeded
100B Content Whitelisted (Testing Retry.

mode)
100C Incomplete Push Request Retried with the valid

Parameters parameter
100d Invalid SMS Data To Send Retry with the data fixed
1024 SMS Site Server achieve Do not Retry

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
1025 Queuing occur SMS Site Retry

Server.
Application / ESME able to

retry since the short message
had not been sent to Billing
Gateway / MMX
1026 Problem occur on connection Retry

between SMS Site Server and
Billing Gateway / MMX

Gateway / MMX
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 No Retry

reached
4.2.3 Delivery Report
4.2.3.1 Delivery Report Format
Size
field Type Description
(octets)

Size
(octets)
id 10 C-Octet String The message ID allocated to the message by the

(Decimal) SMSC when originally submitted.
sub 3 C-Octet String Number of short messages originally submitted.

(Decimal) 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 Number of short messages delivered. This is

Fixed Length only relevant where the original message
String was submitted to a distribution list. The
(Decimal) value is padded with leading zeros if
necessary.
submit 10 C-Octet Fixed The time and date at which the short message
date Length String 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 10 C-Octet Fixed The time and date at which the short message
date Length String reached its final state. The format is the same as
for the submit date.
stat 7 C-Octet Fixed The final status of the message. For settings for
Length String this field see Table B-2.
err 3 C-Octet Fixed Where appropriate this may hold a Network

Length String specific error code or an SMSC error code for the

Size
(octets)
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
Final Message
Message State Description
States
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 Retry

Exceeded
1003 No SMSSS Adapter Retry

1006 Invalid Application Password Retry.
1007 Content Not Active Retry

(Blacklisted, Terminated,
Suspended)
1008 Content Not Registered Retry
1009 Push Quota Per Day Retried after 24 hours

Exceeded
100A Push Quota Per Day Retry

Exceeded
100B Content Whitelisted (Testing Retry.

mode)
100C Incomplete Push Request Retried with the valid

Parameters parameter
100d Invalid SMS Data To Send Retry with the data fixed
1024 SMS Site Server achieve Do not Retry

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
1025 Queuing occur SMS Site Retry

Server.

Gateway / MMX

1026 Problem occur on connection Retry

between SMS Site Server and
Billing Gateway / MMX

Gateway / MMX
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 No Retry

reached
3. External Error Codes.
a. Existing error code triggered by SMSC
Error Code
Status Description Error Handling
Hexa Dec
Do not send same content to

this MSISDN and do not send
other content in 24 hours to
0x500 1280 Rejected Insufficient Balance this MSISDN
Only able to retry after 24

hours to same MSISDN/
Destination
0x502 1282 Rejected Param Sytem Error Should not sent further

Error Code
Hexa Dec
content during 24 hours to

same MSISDN/Destination
Same content not be retried

and should not be sent further
content during 24 hours* to
0x503 1283 Rejected FDA System Error same MSISDN

0x0FE 254 Rejected Delivery Failure his MSISDN
MSISDN Invalid
In case :
MSISDN is not XL
MSISDN or MSISDN
not in White List while
application still in Delete this MSISDN from your
0x011 11 Rejected Testing stage database start from now

Expired / GSM error code- other content in 24 hours to
0x002 2 Undelivered Undefined User this MSISDN

0x001 1 Undelivered Unknown User this MSISDN

0x018 24 Undelivered Switch off station this MSISDN
expired / GSM error code- Do not send same content to

rejected / teleservice not this MSISDN and do not send
0x004 4 undelivered supported other content in 24 hours to

Error Code
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
Delete it and not be

retried and should not be
sent further content
MSISDN during 24 hours to same
0x501 1281 Rejected Invalid MSISDN
Same content not be

0X502
sent further content (Declined - Other)
Internal during 24 hours* to
1282 in Decimal
0x504 1284 Rejected System Error same MSISDN
Same content not be

Not during 24 hours* to
0x504 1285 Authorized same MSISDN

Error Code
Hexa Dec
Same content not be

Service during 24 hours* to
0x504 1286 Barred same MSISDN
Same content not be

Declined / No sent further content
Reserved during 24 hours* to
0x504 1287 balance same MSISDN
Not be retried and

should not be sent
MSISDN further content during 24
0x515 1301 Rejected Suspended hours* to same MSISDN
Delete it and not be

MSISDN during 24 hours to same
0x516 1302 Rejected Terminated MSISDN
Only Able to retry after

24 hours to same
MSISDN/ Destination
Should not send further

content during 24 hours
Balance to same MSISDN/
0x508 1288 Rejected expired 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

Hochgeladen von

Dokumentinformationen

Originalbeschreibung:

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Null

Hochgeladen von

Copyright:

Verfügbare Formate

SMS Gateway

This document contains commercially sensitive information.

Version Date Change

20090504 May 2009 Reflects SMSGW changes starting June 2009

Proprietary and Confidential Page i of 46

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

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.1 New Parameters ................................................................................................................... 15

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 ii of 46

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.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 iii of 46

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