Smpp Specification h2t5v

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) ed 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 name and from Unicel You have more than 10 credits available in case of a prepaid

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

Resolving IP

Smpp1.unicel.in Smpp2.unicel.in

110.234.113.233 110.234.113.233

Connection Port(TRx) 51612, 52612 51612, 52612

Connection Port(Rx) 32612 11612

SSH Port(TRx) 9009, 9901 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 ed Unicel customer utilising the Unicel Gateway for message delivery and receipt. Sender ID: The “from” address that appears on the ’s handset. Also known as the originating number, MSISDN or originator ID. These must be ed within your and approved by us before they may be used. Destination address: This is the number to which the mobile sent the message. Short code: A short number which is common across all the operators for a specific region. Subscriber: The 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 for which you could just send an email to [email protected]. 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 is created by our team, you will receive 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 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 Unicel’s SMPP server by using the below connectivity parameters in their own SMPP Client or Unicel SMPP Client (refer for understanding Unicel’s SMPP Client):

Protocol Description Units (PDUs) ed by Unicel PDU bind_transmitter bind_receiver bind_transceiver submit_sm deliver_sm enquire_link

Response bind_transmitter_resp bind_receiver_resp bind_transceiver_resp submit_sm_resp deliver_sm_resp 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 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 s 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 d_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 ed_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 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 our 24/7 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 subscribers terminating operator is not mapped with the existing status. The message is on SMSC queue i.e. the message has been inserted into the SMSC database but the status of the message is yet to be received.

-01

New Error Code

000

Sub-SMSC

001

DELIVRD

Successfully delivered.

002

FAILED

The message is permanently failed due to CallBarred, Error in Destination Number, Error in TeleService Provider etc.

004

NDNC_Failed

Failed Due to DND Registration

005

Blacklist

Black-listed number. This list of numbers is provided by the customer and includes numbers of CEO etc. A message will never go to a number in the black-list.

006

Whitelist

This error is received when a Opt-In sends messages to a non white listed number

007

Invalid Series

This error is shown when a number series in the correct number format is invalide.

008

Prepaid Reject

This error is shown when the insufficient credits.

031

EXP-AbsSubs

The message is rejected because there was no paging response, 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.

036

EXP-HDST-BUSY

The message is rejected because of congestion encountered at the visited MSC.

EXP-MSG-Q-EXD

Message queue exceeded when there are too many messages for one number. SMSC can deliver only a particular number of messages to a mobile number. If there are more messages, they get this error code till the queue clears.

037

messages are rejected due to

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 ed_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 data: 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 data: 41 41 41 41 41 41 41 41 41 41 42 42 42 42 42 42 data: 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 data: 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 data: 42 43 43 43 43 43 43 43 43 43 43 43 43 43 43 43 data: 43 43 43 43 43 43 43 43 43 43 43 43 43 43 43 43 data: 43 43 43 43 43 43 43 44 44 44 44 44 44 44 44 44 data: 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 data: 44 44 44 44 44 44 44 44 44

AAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAA AAAAAAAAAABBBBBB BBBBBBBBBBBBBBBB BBBBBBBBBBBBBBBB BCCCCCCCCCCCCCCC CCCCCCCCCCCCCCCC CCCCCCCDDDDDDDDD DDDDDDDDDDDDDDDD 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: "Test" 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 ed_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 data: 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 data: 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 data: 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 data: 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 42 data: 42 42 42 42 42 42 42 43 43 43 43 43 43 43 43 43 data: 43 43 43 43 43 43 43 43 43 43 43 43 43 43 43 43 data: 43 43 43 43 43 43 43 43 43 43 43 43 43 44 44 44 data: 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44 data: 44 44 44 44 44 44 44 44 44 44 44 44 44 44 44

......AAAAAAAAAA AAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAA BBBBBBBBBBBBBBBB BBBBBBBBBBBBBBBB BBBBBBBCCCCCCCCC CCCCCCCCCCCCCCCC CCCCCCCCCCCCCDDD DDDDDDDDDDDDDDDD 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 ed_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 data: a5 bd b8 04 00 84 d8 c5 13 81 48 13 81 48 13 81 data: 48 13 81 48 13 81 38 14 81 58 16 81 78 18 81 88 data: 10 61 88 10 61 b8 10 81 18 10 81 88 10 61 88 10 data: 61 68 10 81 78 10 81 88 10 61 88 10 61 b8 10 81 data: 18 10 81 88 10 61 88 10 61 68 10 81 78 10 81 b8 data: 18 81 32 10 81 b8 18 81 22 10 81 b8 18 81 12 10 data: 82 4d c1 44 60 00

.......02J:].... ..........H..H.. H..H..8..X..x... .a..a........a.. ah..x....a..a... .....a..ah..x... ..2....."....... .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 ed_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 data: 63 4e 34 34 37 30 30 30 35 34 20 73 75 62 3a 30 data: 30 31 20 64 6c 76 72 64 3a 30 30 31 20 73 75 62 data: 6d 69 74 20 64 61 74 65 3a 30 38 31 31 32 33 32 data: 32 30 34 20 64 6f 6e 65 20 64 61 74 65 3a 30 38 data: 31 31 32 33 32 32 30 34 20 73 74 61 74 3a 44 45 data: 4c 49 56 52 44 20 65 72 72 3a 30 30 31 20 54 65 data: 78 74 3a 41 41 41 41 41 41 41 41 41 41 41 41 41 data: 41 41 41 41 41 41 41

id:Ua41b9fe0Nb97 cN44700054 sub:0 01 dlvrd:001 sub mit date:0811232 204 done date:08 11232204 stat:DE LIVRD err:001 Te xt:AAAAAAAAAAAAA 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 ed_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