Cloud SMPP

Connection Configuration

Hosts

You can connect to any of the following hosts with your given username and password.

Ports

Please ensure that you choose the correct port for the message encoding you are submitting.

Optionally, we support the SSL/TLS connection.

Bind Operations

There are three ways to open a connection using SMPP. You can connect as:

• Transmitter - send short messages to SMSC and receive responses from SMSC.
• Receiver - receive delivery receipts from the SMSC and return the corresponding responses.
• Transceiver - send and receive messages to and from the SMSC over a single SMPP session.

Session States

Your connection to our server across an SMPP link can be in one of five states:

• OPEN - connected and bind pending
• BOUND_TX - onnected and requested to bind as a Transmitter
• BOUND_RX - connected and requested to bind as a Receiver
• BOUND_TRX - connected and requested to bind as a Transceiver
• CLOSED - unbound and disconnected

Bind Parameters

The syntax for initiating a bind_transmitter, bind_receiver or bind_transceiver instance uses the following parameters:

• system_id - identifies the user requesting to bind (username)
• password - password to allow access
• system_type - identifies the system type (ignored, set to blank)
• interface_version - indicates SMPP version supported by user
• addr_ton - identifies user type of number (ignored, set to blank)
• addr_npi - numbering plan indicator for user (ignored, set to blank)
• address_range - The user address

Submit_sm Parameters

The parameters required for the SUBMIT_SM request (used to send an SMS) are:

• service_type - indicates SMS application service
• sourceaddrton - type of number for source address
• sourceaddrnpi - numbering plan indicator for source address
• source_addr - source address
• destaddrton - type of number for destination
• destaddrnpi - numbering plan indicator for destination
• destination_addr - destination address of the short message
• esm_class - message mode and type
• protocol_id - protocol identifier (network specific)
• priority_flag - sets the priority of the message (this is ignored)
• scheduledeliverytime - set to NULL for immediate delivery (this is ignored)
• validity_period - validity period of message
• registered_delivery - indicator to signify if an SMSC delivery receipt or acknowledgment is required
• replaceifpresent_flag - flag indicating if submitted message should replace an existing message (this is ignored)
• data_coding - defines the encoding scheme of the SMS message
• smdefaultmsg_id - indicates short message to send from a predefined list of messages stored on SMSC (this is ignored)
• sm_length - length in octets of the short_message user data
• short_message - up to 254 octets of short message user data.
• usermessagereference - user assigned reference number

Deliver_sm Parameters

deliversm has the same parameter list as the submitsm request:

• service_type - indicates SMS application service
• sourceaddrton - type of number for source address
• sourceaddrnpi - numbering plan indicator for source address
• source_addr - source address
• destaddrton - type of number for destination
• destaddrnpi - numbering plan indicator for destination
• destination_addr - destination address of the short message
• esm_class - message mode and type
• protocol_id - protocol identifier (network specific)
• priority_flag - sets the priority of the message (this is ignored)
• scheduledeliverytime - set to NULL for immediate delivery (this is ignored)
• validity_period - validity period of message
• registered_delivery - indicator to signify if an SMSC delivery receipt or acknowledgment is required
• replaceifpresent_flag - flag indicating if submitted message should replace an existing message (this is ignored)
• data_coding - defines the encoding scheme of the SMS message
• smdefaultmsg_id - indicates short message to send from a predefined list of messages stored on SMSC (this is ignored)
• sm_length - length in octets of the short_message user data
• short_message - up to 254 octets of short message user data.
• usermessagereference - user assigned reference number

The SMSC delivery receipt is carried as the user data payload in the SMPP deliversm_ operation.

deliversmresp requests require only a messageid_ parameter. Delivery receipts are addressed to the originator of the message.

Transactional Error Codes

To help you identify what might be causing a problem with your SMPP transaction, here is a list of error codes with a small description:

SMPP Commands

The SMS Gateway supports the following SMPP commands:

Note that any command in the SMPP specification which isn't listed above isn't currently supported.

Command States

SMPP supports the following commands through the following SMPP session states:

NB: data_sm, query_sm, cancel_sm, replace_sm and submit_sm_multi aren't supported.

submit_sm and submit_sm_resp transactions will include a message identifier and a status which identifies whether the message is valid or invalid. If invalid, an error status will be returned. Please note that the message identifier will be HEX encoded on SMPP 3.3 connections but will be a standard ASCII encoded integer on SMPP 3.4 connections.

Delivery Receipts

SMPP delivery receipts take the following format:

Format

id:IIIIIIIIII sub:SSS dlvrd:DDD submit date:YYMMDDhhmm done date:YYMMDDhhmm stat:DDDDDDD err:E Text .........

Where:

• id - the message ID allocated to the message by the server
• sub - the number of short messages originally submitted
• dlvrd - the number of short messages delivered
• submit date - the date and time at which the short message was submitted
• done date - the date and time at which the short message reached its final state
• stat - the final status of the message. Please see section 7.0 Message Status for more information.
• err - where appropriate this may hold a network specific error code or an SMSC error code
• text - the first 20 characters of the short message

Note that SMPP v3.3 and v3.4 differ, such that message IDs returned from an SMPP 3.3 connection are encoded as hex whereas 3.4 SMPP connections return message IDs as ASCII encoded integers.

Message Status

The delivery report status indicates whether the SMS message was delivered successfully by the SMSC. If the SMS wasn't successfully delivered, the delivery report will give a reason in the form of an [error code].

SMPP message states and their meanings are listed here for your convenience:

Note that some SMSCs will still return a delivery receipt when a message has been accepted or if the message is buffered in the SMSC. For example, if the handset is switched off. This will use the UNKNOWN state and sets the buffered special parameter in the deliver_sm under SMPP 3.4

Error Codes

Sinch has a record of providing high quality and reliable reporting. Should your message not be delivered, an error code will be returned in the deliver_sm with a reason why.

These are defined here:

Terminology

• MSISDN
  Mobile Subscriber Integrated Services Digital Network: the mobile number in international format.
• MSC
  Mobile Switching Centre: the destination network equipment that receives an SMS (via forward-SM operation) in a destination mobile network.
• HLR
  Home Location Register: the destination network equipment that returns status and routing information about an MSISDN to the SMSC (via SRI-SM operation).
• SMSC
  Short Message Service Centre: the equipment belonging to Sinch or one of its carriers that transmits SMS to the destination network via SS7.
• SS7
  Signalling System 7: the transport protocol that interconnects global GSM networks.
• MNP
  Mobile Number Portability: the process of a subscriber moving from one mobile network to another, but retaining the same MSISDN.
• IMSI
  International Mobile Subscriber Identity: a unique identification number which identifies the destination country, actual network, and network subscriber ID.
• Subscriber
  The mobile user who has a SIM card.