Unicel SMPP Specification

Customer Guide

Document Version: 1.0

Last Revised: January 9, 2013

Copyright Unicel Technologies Pvt. Ltd.

The content of this document are copyright and remain the property of Unicel Technologies Pvt. Ltd. This document
is not to be reproduced in any form, whether electronic, mechanical or by any other means without written permission
of Unicel Technologies Pvt. Ltd.
Table of Contents
Preface............................................................................................................................................. 3
A Few Assumptions ........................................................................................................................ 3
Required Environment: ................................................................................................................... 3
Terminology.................................................................................................................................... 4
Introduction to SMPP Protocol ....................................................................................................... 4
Getting Started ................................................................................................................................ 4
Connecting through SMPP ............................................................................................................. 5
Protocol Description Units (PDUs) supported by Unicel ............................................................... 5
PDUs Description ........................................................................................................................... 5
Delivery reports .............................................................................................................................. 6
Enquire link ..................................................................................................................................... 6
Incoming Messages ......................................................................................................................... 7
Status Codes ................................................................................................................................... 8
Sample PDU.................................................................................................................................... 9
SUBMIT_SM PDU for text message (upto 160 characters) ...................................................... 9
SUBMIT_SM PDU for multipart (concatenated) text messages (153 char message + 6 char
UDH)......................................................................................................................................... 10
SUBMIT_SM PDU for binary message (ringtones, picture messages, WAP Push messages
etc.)............................................................................................................................................ 11
DELIVER_SM PDU for delivery receipt ................................................................................. 12
DELIVER_SM PDU for Incoming MO message ..................................................................... 13
References ..................................................................................................................................... 14
Preface
This guide provides specifications of connecting to Unicel via SMPP. This guide is intended for
developers planning on integrating their systems with SMPP Client/Server Application to
connect to Unicel SMS gateway.

A Few Assumptions

This guide assumes that you are familiar with and have experience applying the following
technologies and concepts:

SMPP Protocol 3.3 or 3.4.

You already have a Username and Password from Unicel
You have more than 10 credits available in case of a prepaid account

Required Environment:

In order to transmit messages via SMPP you would need to have the below ports opened along
white listing.

Domain Resolving IP Connection Connection SSH

Port(TRx) Port(Rx) Port(TRx)
Smpp1.unicel.in 110.234.113.233 51612, 52612 32612 9009, 9901
Smpp2.unicel.in 110.234.113.233 51612, 52612 11612 9009, 9901
Terminology

Mobile originated (MO): A message sent (originating) from a mobile handset to an
application via Unicel.

Mobile terminated (MT): A message sent from an application to (terminating on) a
mobile handset via Unicel.

Customer: A registered Unicel customer utilising the Unicel Gateway for message
delivery and receipt.

Sender ID: The from address that appears on the users handset. Also known as
the originating number, MSISDN or originator ID. These must be registered within
your account and approved by us before they may be used.

Destination address: This is the number to which the mobile user sent the
message.

Short code: A short number which is common across all the operators for a specific
region.

Subscriber: The user handset that will be paying for the MT service.

Gateway: A network operator, third party or our own short message service centre
(SMSC).

SMSC: Short Message Service Centre SMS Gateway

SMPP: Short Message Peer to Peer

ESME: External Short Message Entity

Introduction to SMPP Protocol

The Short Message Peer to Peer (SMPP) protocol is an open industry standard messaging
protocol designed to simplify integration of data applications with wireless mobile networks. The
Unicel SMPP offers an SMPP server connection with the Unicel gateway using our standard
authentication system and error codes.

Connecting via SMPP requires a thorough understanding of the SMPP Protocol. Please read the
SMPP 3.4 specifications available from www.smsforum.net before reading the rest of this
document. This document only contains information on how to connect Unicel SMS Gateway
using SMPP.

Getting Started
In order to test Unicel gateway you need a Unicel Demo account for which you could just send an
email to sales@uniceltech.com. After submitting this online form you will immediately receive an
email confirmation for the same. In case you are not receiving it, kindly drop a mail to sales. Once
the account is created by our support team, you will receive account details on your mail along with
an SMS confirmation.

Normally this demo will remain active for 3 days with a SMS credit of 100. During this demo period
our support and sales team will be there to address all your queries. After successful completion of
Demo, our sales team will help you in converting it into live.
Connecting through SMPP
The Unicel Messaging Platform can act as an SMPP SMSC. Customer can directly send a
connection request to Unicels SMPP server by using the below connectivity parameters in their
own SMPP Client or Unicel SMPP Client (refer for understanding Unicels SMPP Client):

Protocol Description Units (PDUs) supported by Unicel

PDU Response
bind_transmitter bind_transmitter_resp
bind_receiver bind_receiver_resp
bind_transceiver bind_transceiver_resp
submit_sm submit_sm_resp
deliver_sm deliver_sm_resp
enquire_link enquire_link_resp

PDUs Description
Bind transmitter: If application is bind as transmitter, then the ESME or SMPP Client
sends short messages to the SMSC and receives the corresponding SMPP responses from
SMSC.

Bind-receiver: If application is bind as receiver, then the ESME or SMPP Client receives
short messages from the SMSC and returns a corresponding SMPP message response to
the SMSC.

Bind_transceiver: If a calling application bound as transceiver, then the ESME or SMPP

Client sends messages to SMSC and receives messages from SMSC over a single SMPP
session. If this method is selected and the SMSC does not support it, the SMPP Client will
attempt to bind again using Transmitter/Receiver method.

Submit_SM is used by ESME (External Short Message Entity) or SMPP Client to submit
short message to the SMSC for the transmission of the specified short message entity
(SME).Unicel supports two types of messages 1. Short messages (up to 160 characters)
and large messages (more than 160 characters) in its Calling Application.

Deliver_sm is sued by the SMSC to send message to an ESME or SMPP Client regarding
to the message sent by the Client. SMSC returns one unique ID usually called Message ID
and one Error Code. This Error Code describes, what happens with your message which
you have sent means message delivered successfully or not. These Deliver_sm are sent in
response to SMS message whose registerd_delivery parameter requested them.
Enquire_link specifies whether a message can be sent by either SMPP Client or the SMSC
that is used to provide a confidence check of the communication path between SMPP Client
and the SMSC. On receipt of this request the receiving party sends a response that verifies
the application connection between the SMSC and SMPP Client(ESME).Or in short we can
say that it is used by either SMPP Client or SMSC to ping the other side.

Delivery reports

For each message which has been previously submitted with the submit_sm operation and where
delivery report has been requested via the registered_delivery parameter, RoutoMessaging
SMSC will generate delivery report and submit to the appropriate customer through deliver_sm.
The delivery receipt data relating to the original short message will be included in the
short_message field of the deliver_sm.

In order to receive delivery reports over SMPP, you will need to bind as either transceiver or
receiver, since delivery reports cannot be delivered if the customer is bound exclusively as
transmitter. To ensure proper receiving of delivery reports, you would need to verify that your
SMPP client application is able to handle deliver_sm PDUs.

In delivery reports, all time/date related fields will be in ASCII with the following format:

YYYYMMDDhhmm where:
YYYY digits of the year (e.g. 2011)
MM month (01-12)
DD day (01-31)
hh hour (00-23)
mm minute (00-59)

Enquire link
The enquire link commands are used to check the connectivity between ESME and SMSC and
can be issued from both entities.

Please note that our default timeout for these commands is 30 seconds. In case Routo SMSC
does not receive a valid response within 30 seconds after sending the 'enquire_link' command it
will treat the connection as expired.

A common problem which might appear in case there is an unstable IP connection between
ESME and SMSC is that ESME will not receive a valid 'enquire_link_response'. If that happens,
ESME will usually try to establish another 'bind_transmitter', 'bind_transciever' or 'bind_receiver'
command, thus it will increase the number of parallel connections.
Once this number reaches the maximum allowed for parallel connections, all other attempts to
bind will be rejected which resulting in inability for ESME to connect to SMSC.

In case this happens, the customer should contact our 24/7 support team and ask them to delete
these 'ghosts' connections in order to be able to re-establish a valid connection to our SMSC.

Incoming Messages

Another system which is quite popular is an 'incoming' system which provides a customer with a
dedicated number (long international number, not a short code). This number allows you to
receive the message from any location in the world. In other words the sender always sends the
message to that number regardless of his current location and you will receive it over SMPP
protocol ('deliver_sm' SMPP command).
Status Codes

CODE REASON DESCRIPTION

I ) FINAL STATUS
This status displays when the error code provided by the
-01 New Error Code subscribers terminating operator is not mapped with the existing
status.
The message is on SMSC queue i.e. the message has been
000 Sub-SMSC inserted into the SMSC database but the status of the message is
yet to be received.

001 DELIVRD Successfully delivered.

The message is permanently failed due to CallBarred, Error in

002 FAILED
Destination Number, Error in TeleService Provider etc.

004 NDNC_Failed Failed Due to DND Registration

Black-listed number. This list of numbers is provided by the

005 Blacklist customer and includes numbers of CEO etc. A message will never
go to a number in the black-list.
This error is received when a Opt-In account sends messages to a
006 Whitelist
non white listed number

This error is shown when a number series in the correct number

007 Invalid Series
format is invalide.

This error is shown when the messages are rejected due to

008 Prepaid Reject
insufficient credits.
The message is rejected because there was no paging response,
031 EXP-AbsSubs the IMSI record is marked detached, or the MS is subject to
roaming restrictions.

032 EXP-MEM-EXCD Message rejected because the MS doesn't have enough memory.

033 EXP-NW-FAIL Message rejected due to network failure.

034 EXP-NW-TMOUT Message rejected due to network or protocol failure.

035 EXP-SMS-TMOUT Message rejected due to network or protocol failure.

The message is rejected because of congestion encountered at

036 EXP-HDST-BUSY
the visited MSC.
Message queue exceeded when there are too many messages for
one number. SMSC can deliver only a particular number of
037 EXP-MSG-Q-EXD
messages to a mobile number. If there are more messages, they
get this error code till the queue clears.
Sample PDU
Should you have any trouble integrating your SMPP Client with Unicel SMPP server, you may
want to capture the SMPP transaction using network sniffing protocol such as wireshark/ethereal
or using your own SMPP application. Following PDU may be used as point of reference:

SUBMIT_SM PDU for text message (upto 160 characters)

SMPP PDU 0xb6000870 dump:

`type_name: submit_sm
command_id: 4 = 0x00000004
command_status: 0 = 0x00000000
service_type: NULL
source_addr_ton: 5 = 0x00000005
source_addr_npi: 0 = 0x00000000
source_addr: "Test"
dest_addr_ton: 1 = 0x00000001
dest_addr_npi: 1 = 0x00000001
destination_addr: "919980524000"
esm_class: 3 = 0x00000003
protocol_id: 0 = 0x00000000
priority_flag: 3 = 0x00000003
schedule_delivery_time: NULL
validity_period: NULL
registered_delivery: 1 = 0x00000001
replace_if_present_flag: 0 = 0x00000000
data_coding: 0 = 0x00000000
sm_default_msg_id: 0 = 0x00000000
sm_length: 153 = 0x00000099
short_message:
Octet string at 0xb60004e8:
len: 153
size: 154
data: 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 AAAAAAAAAAAAAAAA
data: 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 AAAAAAAAAAAAAAAA
data: 41 41 41 41 41 41 41 41 41 41 42 42 42 42 42 42 AAAAAAAAAABBBBBB
data: 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 BBBBBBBBBBBBBBBB
data: 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 BBBBBBBBBBBBBBBB
data: 42 43 43 43 43 43 43 43 43 43 43 43 43 43 43 43 BCCCCCCCCCCCCCCC
data: 43 43 43 43 43 43 43 43 43 43 43 43 43 43 43 43 CCCCCCCCCCCCCCCC
data: 43 43 43 43 43 43 43 44 44 44 44 44 44 44 44 44 CCCCCCCDDDDDDDDD
data: 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 DDDDDDDDDDDDDDDD
data: 44 44 44 44 44 44 44 44 44 DDDDDDDDD
SUBMIT_SM PDU for multipart (concatenated) text messages (153 char
message + 6 char UDH)

SMPP PDU 0xb6000870 dump:

type_name: submit_sm
command_id: 4 = 0x00000004
command_status: 0 = 0x00000000
sequence_number: 13980 = 0x0000369c
service_type: NULL
source_addr_ton: 5 = 0x00000005
source_addr_npi: 0 = 0x00000000
source_addr: "TestUser"
dest_addr_ton: 1 = 0x00000001
dest_addr_npi: 1 = 0x00000001
destination_addr: "919980524000"
esm_class: 67 = 0x00000043
protocol_id: 0 = 0x00000000
priority_flag: 3 = 0x00000003
schedule_delivery_time: NULL
validity_period: NULL
registered_delivery: 1 = 0x00000001
replace_if_present_flag: 0 = 0x00000000
data_coding: 0 = 0x00000000
sm_default_msg_id: 0 = 0x00000000
sm_length: 159 = 0x0000009f
short_message:
Octet string at 0xb60004e8:
len: 159
size: 1024
immutable: 0
data: 05 00 03 10 02 01 41 41 41 41 41 41 41 41 41 41 ......AAAAAAAAAA
data: 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 AAAAAAAAAAAAAAAA
data: 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 AAAAAAAAAAAAAAAA
data: 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 BBBBBBBBBBBBBBBB
data: 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 BBBBBBBBBBBBBBBB
data: 42 42 42 42 42 42 42 43 43 43 43 43 43 43 43 43 BBBBBBBCCCCCCCCC
data: 43 43 43 43 43 43 43 43 43 43 43 43 43 43 43 43 CCCCCCCCCCCCCCCC
data: 43 43 43 43 43 43 43 43 43 43 43 43 43 44 44 44 CCCCCCCCCCCCCDDD
data: 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 DDDDDDDDDDDDDDDD
data: 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 DDDDDDDDDDDDDDD
SUBMIT_SM PDU for binary message (ringtones, picture messages, WAP Push
messages etc.)

SMPP PDU 0xb6000870 dump:

type_name: submit_sm
command_id: 4 = 0x00000004
command_status: 0 = 0x00000000
sequence_number: 13983 = 0x0000369f
service_type: NULL
source_addr_ton: 1 = 0x00000001
source_addr_npi: 1 = 0x00000001
source_addr: "919880015015"
dest_addr_ton: 2 = 0x00000001
dest_addr_npi: 1 = 0x00000001
destination_addr: "919980524000"
esm_class: 67 = 0x00000043
protocol_id: 0 = 0x00000000
priority_flag: 3 = 0x00000003
schedule_delivery_time: NULL
validity_period: NULL
registered_delivery: 1 = 0x00000001
replace_if_present_flag: 0 = 0x00000000
data_coding: 4 = 0x00000004
sm_default_msg_id: 0 = 0x00000000
sm_length: 118 = 0x00000076
short_message:
Octet string at 0xb60004d0:
len: 118
size: 1024
immutable: 0
data: 06 05 04 15 81 15 81 30 32 4a 3a 5d b5 a5 cd cd .......02J:]....
data: a5 bd b8 04 00 84 d8 c5 13 81 48 13 81 48 13 81 ..........H..H..
data: 48 13 81 48 13 81 38 14 81 58 16 81 78 18 81 88 H..H..8..X..x...
data: 10 61 88 10 61 b8 10 81 18 10 81 88 10 61 88 10 .a..a........a..
data: 61 68 10 81 78 10 81 88 10 61 88 10 61 b8 10 81 ah..x....a..a...
data: 18 10 81 88 10 61 88 10 61 68 10 81 78 10 81 b8 .....a..ah..x...
data: 18 81 32 10 81 b8 18 81 22 10 81 b8 18 81 12 10 ..2.....".......
data: 82 4d c1 44 60 00 .M.D`.
DELIVER_SM PDU for delivery receipt

SMPP PDU 0xb2e005a0 dump:

type_name: deliver_sm
command_id: 5 = 0x00000005
command_status: 0 = 0x00000000
sequence_number: 0 = 0x00000000
service_type: NULL
source_addr_ton: 1 = 0x00000001
source_addr_npi: 1 = 0x00000001
source_addr: "Test"
dest_addr_ton: 1 = 0x00000001
dest_addr_npi: 1 = 0x00000001
destination_addr: "919980524000"
esm_class: 4 = 0x00000004
protocol_id: 0 = 0x00000000
priority_flag: 3 = 0x00000003
schedule_delivery_time: NULL
validity_period: NULL
registered_delivery: 0 = 0x00000000
replace_if_present_flag: 0 = 0x00000000
data_coding: 0 = 0x00000000
sm_default_msg_id: 0 = 0x00000000
sm_length: 135 = 0x00000087
short_message:
Octet string at 0xb2e00690:
len: 135
size: 136
immutable: 0
data: 69 64 3a 55 61 34 31 62 39 66 65 30 4e 62 39 37 id:Ua41b9fe0Nb97
data: 63 4e 34 34 37 30 30 30 35 34 20 73 75 62 3a 30 cN44700054 sub:0
data: 30 31 20 64 6c 76 72 64 3a 30 30 31 20 73 75 62 01 dlvrd:001 sub
data: 6d 69 74 20 64 61 74 65 3a 30 38 31 31 32 33 32 mit date:0811232
data: 32 30 34 20 64 6f 6e 65 20 64 61 74 65 3a 30 38 204 done date:08
data: 31 31 32 33 32 32 30 34 20 73 74 61 74 3a 44 45 11232204 stat:DE
data: 4c 49 56 52 44 20 65 72 72 3a 30 30 31 20 54 65 LIVRD err:001 Te
data: 78 74 3a 41 41 41 41 41 41 41 41 41 41 41 41 41 xt:AAAAAAAAAAAAA
data: 41 41 41 41 41 41 41 AAAAAAA
DELIVER_SM PDU for Incoming MO message

SMPP PDU 0x86e4fd0 dump:

type_name: deliver_sm
command_id: 5 = 0x00000005
command_status: 0 = 0x00000000
sequence_number: 0 = 0x00000000
service_type: NULL
source_addr_ton: 1 = 0x00000001
source_addr_npi: 1 = 0x00000001
source_addr: "919880015015"
dest_addr_ton: 1 = 0x00000001
dest_addr_npi: 1 = 0x00000001
destination_addr: "919845198451"
esm_class: 0 = 0x00000000
protocol_id: 0 = 0x00000000
priority_flag: 3 = 0x00000003
schedule_delivery_time: NULL
validity_period: NULL
registered_delivery: 0 = 0x00000000
replace_if_present_flag: 0 = 0x00000000
data_coding: 0 = 0x00000000
sm_default_msg_id: 0 = 0x00000000
sm_length: 43 = 0x0000002b
short_message:
Octet string at 0x86e5108:
len: 43
size: 44
immutable: 0
data: 41 61 61 61 61 61 61 61 61 61 61 61 61 62 62 62 Aaaaaaaaaaaaabbb
data: 62 62 62 62 62 62 62 62 62 62 62 62 62 62 62 62 bbbbbbbbbbbbbbbb
data: 62 63 63 63 63 63 63 63 63 63 63 bcccccccccc
References
The following is the list of references:

a. SMPP v.3.4 http://www.smsforum.net

b. SMPP - http://en.wikipedia.org/wiki/Short_message_peer-to-peer_protocol

c. GSM 03.38 - http://en.wikipedia.org/wiki/SMS#GSM

d. ITU-T numbering - http://en.wikipedia.org/wiki/E.164