SMSGH Unity SMPP API SPECIFICATIONS Table of Contents Overview ...........................................................................................................................................2 Supported PDUs .................................................................................................................................2 Bind and Authentication .....................................................................................................................3 How to get connected.........................................................................................................................3 BIND Operation ..........................................................................................................................3 BIND_TRANSMITTER .......................................................................................................4 BIND_TRANSMITTER_RESP .............................................................................................5 BIND_RECEIVER................................................................................................................5 BIND_RECEIVER_RESP......................................................................................................6 BIND_TRANSCEIVER ........................................................................................................7 BIND_TRANSCEIVER_RESP ..............................................................................................8 SMPP PDUs Parameters definition .......................................................................................................8 SUBMIT_SM Operation...............................................................................................................9 SUBMIT_SM_RESP Operation................................................................................................... 12 CANCEL_SM Operation............................................................................................................ 13 CANCEL_SM_RESP Operation.................................................................................................. 14 QUERY_SM Operation .............................................................................................................. 15 QUERY_SM_RESP Operation.................................................................................................... 15 ENQUIRE_LINK Operation........................................................................................................ 17 ENQUIRE_LINK_RESP Operation ............................................................................................. 17 DELIVER_SM Operation............................................................................................................ 17 DELIVER_SM_RESP .................................................................................................................... 20 ERROR CODES............................................................................................................................... 20 Overview This document is intended to those who will want to develop applications that make use of our SMS gateway via the SMPP protocol. To be able to use this API the ESME must be an API account holder with SMSGH Ltd. Please bear with us that this documentation is not handling the creation of an API account. It is providing the details on how to use the SMPP API. The versions of SMPP Protocol supported by the API are version 3.3 and 3.4. Anyone with knowledge in SMPP 3.3 and 3.4 protocol can easily use our API because the API is designed according the standard specifications. Supported PDUs The following PDUs are currently handled by the SMPP API: Clie nt to Se rve r Se rve r to Clie nt bind_transmitte r bind_transmitte r_re sp bind_re ce ive r bind_re ce ive r_re sp bind_transce ive r bind_transce ive r_re sp submit_sm submit_sm_re sp que ry_sm que ry_sm_re sp cance l_sm cance l_sm_re sp e nquiry_link e nquiry_link_re sp de live r_sm_re sp de live r_sm Bind and Authentication To be able to bind one needs an SMSGH API account. During the bind request the following fields name are required: syste m_id : It will hold the API public key passw ord : It will hold the API private key interface_version : It will hold the interface version of the protocol used syste m_type : It will hold the API Identifier Only one binding is allowed for a given API Identifier. However based upon some rules on the API account you may be allowed to bind more than once using the same API public key. An ESME can use all the bind PDUs required by the SMPP 3.4. So an ESME can bind as: Transceiver Transmitter Receiver How to get connected To be able to obtain an SMPP connection one needs to have an SMSGH AP I account and then send a Bind request to the SMSGH SMPP Server over the TCP/IP network. So SMPP connection is done via a bind request. BIND Operation The purpose of the SMPP bind operation is to register an instance of an ESME with the SMSC system and request an SMPP session over this network connection for the submission or delivery of messages. Thus, the Bind operation may be viewed as a form of SMSC login request to authenticate the ESME entity wishing to establish a connection. As described previously, an ESME may bind to the SMSGH SMPP Server as either a Transmitter (called ESME Transmitter), a Receiver (called ESME Receiver) or a Transceiver (called ESME Transceiver).There are three SMPP bind PDUs to support the various modes of operation, namely bind_transmitte r , bind_transce ive r and bind_re ce ive r . The command_id field setting specifies which PDU is being used. BIND_TRANSMITTER Fie ld Name Size H E A D E R Type De scription Integer Defines the overall length of the Octe ts command_length 4 bind_transmitte r PDU command_id 4 Integer bind_transmitte r command_status 4 Integer Not used set to NULL sequence_number 4 Integer Set to a Unique sequence number. The associated bind_transmitter_resp PDU will echo this sequence number BODY MANDATORY PARAMETERS system_id Var. max C-Octet String It will hold the ESME API public key Var. C-Octet It will hold the ESME API private key max String 16 password 9 interface_version 1 Integer Indicates the version of the SMPP protocol supported by the ESME. Here the version supported are 3.3 and 3.4 system_type Var. C-Octet max String It will hold the ESME API Identifier 13 addr_ton addr_npi addr_range 1 Integer set to NULL or 00000001(0x01) 1 Integer set to NULL or 00000001(0x01) Var. C-Octet The ESME IP address. max String If not known, set to NULL. Type De scription 41 BIND_TRANSMITTER_RESP Fie ld Name H Size Octe ts E A command_length 4 Integer Defines the overall length of the bind_transmitte r_re sp PDU. D command_id 4 Integer bind_transmitte r_re sp command_status 4 Integer Indicates outcome of E R bind_transmitte r request sequence_number 4 Integer Set to sequence number of original bind_transmitte r request BODY system_id Var. max 16 sc_interface_version C-Octet SMSGH SMPP identifier. String Identifies the SMSC to the ESME. TLV SMPP version supported by SMSGH SMPP Server BIND_RECEIVER Fie ld Name Size Type De scription H E A D E R Octe ts command_length 4 Integer Defines the overall length of the command_id 4 Integer bind_re ce ive r PDU bind_re ce ive r command_status 4 Integer Not used set to NULL sequence_number 4 Integer Set to a Unique sequence number. The associated bind_re ce ive r _re sp PDU will echo this sequence number BODY MANDATORY PARAMETERS system_id Var. C-Octet max String It will hold the ESME API public key 16 password Var. C-Octet max String It will hold the ESME API private key 9 interface_version 1 Integer Indicates the version of the SMPP protocol supported by the ESME. Here the version supported are 3.3 and 3.4 system_type Var. C-Octet max String It will hold the ESME API Identifier 13 addr_ton 1 Integer set to NULL or 00000001(0x01) addr_npi 1 Integer set to NULL or 00000001(0x01) Var. max C-Octet String The ESME IP address. If not known, set to NULL. Type De scription addr_range 41 BIND_RECEIVER_RESP Fie ld Name H Size Octe ts E command_length 4 Integer bind_re ce ive r _re sp PDU. A D E Defines the overall length of the command_id 4 Integer bind_re ce ive r _re sp command_status 4 Integer Indicates outcome of bind_re ce ive r request sequence_number 4 Integer Set to sequence number of R original bind_re ce ive r request BODY system_id Var. max 16 sc_interface_version C-Octet SMSGH SMPP identifier. String Identifies the SMSC to the ESME. TLV SMPP version supported by SMSGH SMPP Server BIND_TRANSCEIVER Fie ld Name Size H Type De scription Octe ts E A command_length 4 Integer Defines the overall length of the bind_transce ive r PDU D command_id 4 Integer bind_transce ive r command_status 4 Integer Not used set to NULL sequence_number 4 Integer Set to a Unique sequence number. E R The associated bind_transceiver_resp PDU will echo this sequence number BODY MANDATORY PARAMETERS system_id Var. C-Octet max String It will hold the ESME API public key 16 password Var. max 9 C-Octet String It will hold the ESME API private key interface_version 1 Integer Indicates the version of the SMPP protocol supported by the ESME. Here the version supported are 3.3 and 3.4 system_type Var. C-Octet max String It will hold the ESME API Identifier 13 addr_ton 1 Integer set to NULL or 00000001(0x01) addr_npi 1 Integer set to NULL or 00000001(0x01) Var. C-Octet The ESME IP address. max String If not known, set to NULL. Type De scription Integer Defines the overall length of the addr_range 41 BIND_TRANSCEIVER_RESP Fie ld Name H E Size Octe ts command_length 4 A D E R bind_transce ive r_re sp PDU. command_id 4 Integer bind_transce ive r_re sp command_status 4 Integer Indicates outcome of bind_transce ive r request sequence_number 4 Integer Set to sequence number of original bind_transce ive r request BODY system_id sc_interface_version Var. max 16 C-Octet String SMSGH SMPP identifier. Identifies the SMSC to the ESME. TLV SMPP version supported by SMSGH SMPP Server SMPP PDUs Parameters definition SUBMIT_SM Operation The submit_sm is used by an ESME to submit a short message to the SMSC for onward transmission to a specified short message entity (SME). The submit_sm PDU does not support the transaction message mode. Fie ld Name Size Octe ts H Type De scription E command_length 4 Integer Not used set to NULL A D command_id 4 Integer submit_sm E command_status 4 Integer Not used set to NULL sequence_number 4 Integer Set to a Unique sequence number. R The associated submit_sm_re sp PDU will echo this sequence number BODY MANDATORY PARAMETERS service_type Var. C-Octet The service_type parameter can be max String 6 used to indicate the SMS Application service associated with the message. Specifying the service_type allows the ESME to • avail of enhanced messaging services such as “replace by service” type • To control the teleservice used on the air interface. Set to NULL for default source_addr_ton 1 Integer set to NULL or 00000001(0x01) source_addr_npi 1 Integer set to NULL or 00000001(0x01) source_addr Var. C-Octet Address of SME which originated max String 21 this message. Must always be set. dest_addr_ton 1 Integer set to NULL or 00000001(0x01) dest_addr_npi 1 Integer set to NULL or 00000001(0x01) destination_addr Var. C-Octet Destination address of this short max 21 String message. For mobile terminated messages, this is the directory number of the recipient MS. Must always be set esm_class 1 Integer Set it to 0x00 protocol_id 1 Integer set it according to the GSM 03.40 standard priority_flag 1 Integer Possible values to set are: 0 = Level 0 (lowest) priority 1 = Level 1 priority 2 = Level 2 priority 3 = Level 3 (highest) priority schedule_delivery_time 1 or 17 C-Octet The String short message is to be scheduled by the SMSC for delivery. Set to NULL for immediate message delivery. validity_period 1 or 17 C-Octet The validity period of this message. String Set to NULL to request the SMSC default validity period registered_delivery 1 Integer Indicator to signify if an SMSC delivery receipt or an SME acknowledgement is required replace_if_present_flag 1 Integer Set to 0 Don’t replace (default) data_coding 1 Integer Defines the encoding scheme of the short message user data. Values supported are: 0x00(00000000) = default 0x03 (00000011) = Latin 1 (ISO-8859-1) 0x08 (00001000) = UCS2 (ISO/IEC-10646) 0x04(00000100) = Octet unspecified (8-bit binary) sm_default_msg_id 1 Integer set to NULL sm_length 1 Integer Length in octets of the short_message user data short_message Var. 0-254 Octet String Applications which need to send messages longer than 254 octets should use the message_payload parameter. In this case the sm_length field should be set to zero. Note : The short message data should be inserted in either the short_message or message_payload fields. Both fields must not be used simultaneously. OPTIONAL PARAMETERS SUPPORTED user_message_reference TLV ESME assigned message reference number. Set this value when registered_delivery is set. dest_addr_subunit TLV The subcomponent in the destination device for which the user data is intended. Supported values are: 0x00 = Unknown (default) 0x01 = MS Display 0x02 = Mobile Equipment 0x03 = Smart Card 1 (expected to be SIM if a SIM exists in the MS) 0x04 = External Unit 1 Note : It must be set to one of the above value message_payload TLV Contains the message extended short user data. Up to 64K octets can be transmitted. Note : The short message data should be inserted in either the short_message or message_payload fields. Both fields should not be used simultaneously. The sm_length field should be set to zero if using the message_payload parameter. Note: All other optional parameters of the submit_sm operation of the SMPP 3.4 are well supported and can be set. SUBMIT_SM_RESP Operation This is the response to the submit_sm PDU and has the following format: Fie ld Name H Size Type De scription Octe ts E command_length 4 Integer Not used set to NULL A command_id 4 Integer submit_sm_re sp command_status 4 Integer Indicates outcome of D E R submit_sm request sequence_number 4 Integer Set to sequence number of original submit_sm PDU BODY message_id Var. max 65 C-Octet This field String message ID contains of the the SMSC submitted message. It may be used at a later stage to query the status of a message, cancel message. or replace the CANCEL_SM Operation This PDU is only used to cancel messages that previously were scheduled to be sent. It is used to cancel one message at a time seeing we do not currently support batch cancelling. Fie ld Name H E A D E R Size Type De scription Octe ts command_length 4 Integer Not used set to NULL command_id 4 Integer cance l_sm command_status 4 Integer Not used set to NULL sequence_number 4 Integer Set to a Unique sequence number. The associated cance l_sm_re sp PDU will echo this sequence number MANDATORY PARAMETERS service_type Var. C-Octet The service_type parameter can be max 6 String used to indicate the SMS Application service associated with the message. Specifying the service_type allows the ESME to • avail of enhanced messaging services such as “replace by service” type • To control the teleservice used on the air interface. Set to NULL for default message_id Var. C-Octet Message ID of the message to be max String cancelled. This must be the SMSC 65 assigned Message ID of the original message. Never set to NULL because we don’t support batch cancelling source_addr_ton 1 Integer set to NULL or 00000001(0x01) source_addr_npi 1 Integer set to NULL or 00000001(0x01) Var. C-Octet Source address of message(s) to be max 21 String cancelled. verification source_addr This is purposes, used for and must match that supplied in the original message submission request PDU(s). Must be set. dest_addr_ton 1 Integer set to NULL or 00000001(0x01) dest_addr_npi 1 Integer set to NULL or 00000001(0x01) Var. max C-Octet String Destination address of message(s) to be cancelled. destination_addr 21 This is used for purposes, and must verification match that supplied in the original message submission request PDU. May be set to NULL when the message_id is provided CANCEL_SM_RESP Operation Fie ld Name H E A D E R Size Type De scription Octe ts command_length 4 Integer Not used set to NULL command_id 4 Integer cance l_sm_re sp command_status 4 Integer Indicates outcome of cance l_sm request sequence_number 4 Integer Set to sequence number of original cance l_sm PDU QUERY_SM Operation Fie ld Name H E A D E R Size Type De scription Octe ts command_length command_id 4 Integer Not used set to NULL 4 Integer que ry_sm command_status 4 Integer Not used set to NULL sequence_number 4 Integer Set to a Unique sequence number. The associated que ry_sm_re sp PDU will echo this sequence number MANDATORY PARAMETERS message_id Var. max C-Octet String 65 Message ID of the message whose state is to be queried. This must be the SERVER assigned Message ID allocated to the original short message when submitted to the SERVER command, by the and submit_sm, returned in the response PDU by the SERVER. source_addr_ton 1 Integer set to NULL or 00000001(0x01) source_addr_npi 1 Integer set to NULL or 00000001(0x01) Var. C-Octet Address of message originator. max String This source_addr 21 is purposes, used and for must verification match that supplied in the original request PDU (e.g. submit_sm ). If not known, set to NULL QUERY_SM_RESP Operation Fie ld Name H E A D E R Size Type De scription Octe ts command_length 4 Integer Not used set to NULL command_id 4 Integer que ry_sm_re sp command_status 4 Integer Indicates outcome of que ry_sm request sequence_number 4 Integer Set to sequence number of original que ry_sm PDU BODY message_id Var. max 65 final_date 1 or 17 C-Octet SMSC Message ID of the message String whose state is being queried. C-Octet Date and time when the queried String message reached a final state. For messages which have not yet reached a final state this field will contain a single NULL octet. message_state 1 Integer Specifies the status of the queried short message. The possible values are: error_code 1 Integer 1 = ENROUTE 2 = DELIVERED 3 = EXPIRED 4 = DELETED 5 = UNDELIVERABLE 6 = ACCEPTED 7 = UNKNOWN 8 = REJECTED Where appropriate this holds a network error code defining the reason for failure of message delivery. The range of values this field may have depends entirely on the underlying telecommunications network. ENQUIRE_LINK Operation Field Name Size Type De scription H E command_length 4 Integer Not used set to NULL A command_id 4 Integer e nquire_link command_status 4 Integer Not used. Set to NULL sequence_number 4 Integer Set to a unique sequence number. The associated e nquire_link_resp D E R Octe ts PDU should echo the same sequence number ENQUIRE_LINK_RESP Operation Field Name H E A D E R Size Type De scription Octe ts command_length 4 Integer Not used set to NULL command_id 4 Integer e nquire_link_resp command_status 4 Integer Set to ESME_ROK (Success) sequence_number 4 Integer Set to the same sequence number of original e nquire_link PDU DELIVER_SM Operation Field Name H E A D Size Type De scription Octe ts command_length 4 Integer Not used set to NULL command_id 4 Integer de liver_sm command_status 4 Integer Not used set to NULL E sequence_number 4 Integer R Set to a Unique sequence number. The associated de liver_sm_resp PDU will echo this sequence number MANDATORY PARAMETERS service_type Var. C-Octet The service_type parameter can be max String 6 used to indicate the SMS Application service associated with the message source_addr_ton source_addr_npi 1 Integer set to NULL or 00000001(0x01) 1 Integer set to NULL or 00000001(0x01) source_addr Var. C-Octet Address of SME which originated max String 21 this message. If not known, set to NULL (Unknown). dest_addr_ton 1 Integer set to NULL or 00000001(0x01) dest_addr_npi 1 Integer set to NULL or 00000001(0x01) destination_addr Var. C-Octet Destination address of destination max 21 String SME. esm_class 1 Integer Set it to 0x00 protocol_id 1 Integer set it according to the GSM 03.40 standard priority_flag 1 Integer Possible values to set are: 0 = Level 0 (lowest) priority 1 = Level 1 priority 2 = Level 2 priority 3 = Level 3 (highest) priority schedule_delivery_time validity_period 1 or C-Octet Set to NULL 17 String 1 or 17 C-Octet Set to NULL String registered_delivery 1 Integer Set to 0x00. replace_if_present_flag 1 Integer Set to NULL data_coding 1 Integer Defines the encoding scheme of the short message user data. Values supported are: 0x00(00000000) = default 0x03 (00000011) = Latin 1 (ISO-8859-1) 0x08 (00001000) = UCS2 (ISO/IEC-10646) 0x04(00000100) = Octet unspecified (8-bit binary) sm_default_msg_id 1 Integer set to NULL sm_length 1 Integer Length in octets of the short_message user data short_message Var. Octet Applications which need to send 0-254 String messages longer than 254 octets should use the message_payload parameter. In this case the sm_length field should be set to zero. Note: The short message data should be inserted in either the short_message or message_payload fields. Both fields must not be used simultaneously. OPTIONAL PARAMETERS SUPPORTED user_message_reference TLV A reference assigned by the originating SME to the message. In the case that the de liver_sm is carrying an SMSC delivery receipt, an SME delivery acknowledgement or an SME user acknowledgement (as indicated in the esm_class field), the user_message_reference parameter is set to the message reference of the original message network_error_code TLV Network Error Code. In case of errors it will be present for Intermediate Notifications and SMSC Delivery Receipts message_state TLV Message State. receipted_message_id TLV SMSC message ID of receipted message. Should be present for SMSC Delivery Receipts DELIVER_SM_RESP Fie ld Name H E A D E R Size Type De scription Octe ts command_length command_id 4 Integer Not used set to NULL 4 Integer de live r_sm_re sp command_status 4 Integer Indicates outcome of de live r_sm request sequence_number 4 Integer Set to sequence number of original de live r_sm PDU BODY message_id Var. max 65 C-Octet Unused. Set to NULL String ERROR CODES Error Code Value De scription ESME_ROK 0x00000000 No Error ESME_RINVMSGLEN 0x00000001 Message Length is invalid ESME_RINVCMDLEN 0x00000002 Command Length is invalid ESME_RINVCMDID 0x00000003 Invalid Command ID ESME_RINVBNDSTS 0x00000004 Incorrect BIND Status for given command ESME_RALYBND 0x00000005 ESME Already in Bound State or Exceed the Number of Bind limits. ESME_RINVPRTFLG 0x00000006 Invalid Priority Flag ESME_RINVREGDLVFLG 0x00000007 Invalid Registered Delivery Flag ESME_RSYSERR 0x00000008 System Error ESME_RINVSRCADR 0x0000000A Invalid Source Address ESME_RINVDSTADR 0x0000000B Invalid Destination Addr ESME_RINVMSGID 0x0000000C Message ID is invalid ESME_RBINDFAIL 0x0000000D Bind Failed ESME_RINVPASWD 0x0000000E Invalid Password ESME_RINVSYS ID 0x0000000F Invalid System ID ESME_RCANCELFAIL 0x00000011 Cancel SM Failed ESME_RREPLACEFAIL 0x00000013 Replace SM Failed ESME_RMSGQFUL 0x00000014 Message Queue Full ESME_RINVSERTYP 0x00000015 Invalid Service Type ESME_RINVESMCLASS 0x00000043 Invalid esm_class field data ESME_RSUBMITFAIL 0x00000045 submit_sm failed ESME_RINVSRCTON 0x00000048 Invalid Source address TON ESME_RINVSRCNPI 0x00000049 Invalid Source address NPI ESME_RINVDSTTON 0x00000050 Invalid Destination address TON ESME_RINVDSTNPI 0x00000051 Invalid Destination address NPI ESME_RINVSYSTYP 0x00000053 Invalid system_type field ESME_RINVREPFLAG 0x00000054 Invalid replace_if_present flag ESME_RINVNUMMSGS 0x00000055 Invalid number of messages ESME_RTHROTTLED 0x00000058 Throttling error (ESME has exceeded allowed message limits) ESME_RINVSCHED 0x00000061 Invalid Scheduled Delivery Time ESME_RINVEXPIRY 0x00000062 Invalid message validity period (Expiry time) ESME_RINVDFTMSGID 0x00000063 Predefined Message Invalid or Not Found ESME_RQUERYFAIL 0x00000067 query_sm request failed ESME_RINVOPTPARSTREAM 0x000000C0 Error in the optional part of the PDU Body. ESME_ROPTPARNOTALLWD 0x000000C1 Optional Parameter not allowed ESME_RINVPARLEN 0x000000C2 Invalid Parameter Length. ESME_RMISSINGOPTPARAM 0x000000C3 Expected Optional Parameter missing ESME_RINVOPTPARAMVAL 0x000000C4 Invalid Optional Parameter Value ESME_RUNKNOWNERR 0x000000FF Unknown Error ESME_NOCR 0x00000400 ESME is out of credit ESME_UNROUTABLE 0x00000401 The message is not routable - check phone number ESME_DATA_UNAUTH 0x00000402 The message is not authorized ESME_LIMIT_EXCESS 0x00000403 The user has exceeded submission Throttling ESME_MESSAGE_TOO_LONG 0x00000404 limits. The user has sent a long message even though it may be a valid length according to the SMPP specifications.