Sinch Developer Documentation

Building blocks to enable rich customer communication

Cloud SMPP

Our Cloud SMPP service is available to you immediately after creating an account on our site. It uses the same core platform and backend connections as our Enterprise SMPP service.

Connection Configuration

SMPP Version3.3 or 3.4
Bind TypeTransmitter, Receiver or Transceiver
Service Type, auth TON and auth NPIAll values are ignored and can be blank
Asynchronous outstanding operations window10
Maximum allowed sessions3

Hosts

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

HostLocation
sms-cloud-1.clxcommunications.comLondon, UK
sms-cloud-2.clxcommunications.comVirginia, US
sms-cloud-3.clxcommunications.comDallas, US
sms-cloud-5.clxcommunications.comFrankfurt, Germany

Ports

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

EncodingPort
GSM, Unicode & Binary8000
Latin 1 (ISO-8859-1)9000

Optionally, we support the SSL/TLS connection.

EncodingPort
GSM, Unicode & Binary8443
Latin 1 (ISO-8859-1)9443

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
  • source_addr_ton - type of number for source address
  • source_addr_npi - numbering plan indicator for source address
  • source_addr - source address
  • dest_addr_ton - type of number for destination
  • dest_addr_npi - 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)
  • schedule_delivery_time - 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
  • replace_if_present_flag - flag indicating if submitted message should replace an existing message (this is ignored)
  • data_coding - defines the encoding scheme of the SMS message
  • sm_default_msg_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.
  • user_message_reference - user assigned reference number

Deliver_sm Parameters

deliver_sm has the same parameter list as the submit_sm request:

  • service_type - indicates SMS application service
  • source_addr_ton - type of number for source address
  • source_addr_npi - numbering plan indicator for source address
  • source_addr - source address
  • dest_addr_ton - type of number for destination
  • dest_addr_npi - 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)
  • schedule_delivery_time - 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
  • replace_if_present_flag - flag indicating if submitted message should replace an existing message (this is ignored)
  • data_coding - defines the encoding scheme of the SMS message
  • sm_default_msg_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.
  • user_message_reference - user assigned reference number

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

deliver_sm_resp requests require only a message_id 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:

CodeDescription
0No error
3Invalid command ID
4Invalid bind status for given command
5ESME already in bound state
10Invalid source address
12Message ID is invalid
13Bind failed
14Invalid password
15Invalid system ID
20Message queue full
21Invalid system type
97Invalid scheduled delivery time
98Invalid message delivery period

SMPP Commands

The SMS Gateway supports the following SMPP commands:

CommandDescriptionHEX Code
generic_nackGeneric ‘Not Acknowledged’ status0x80000000
bind_receiverBinds as ‘Receiver’0x00000001
bind_receiver_respResponse to bind_receiver0x80000001
bind_transmitterBinds as ‘Transmitter’0x00000002
bind_transmitter_respResponse to bind_transmitter0x80000002
submit_smSubmit an SMS message0x00000004
submit_sm_respResponse to submit_sm_resp0x80000004
deliver_smReceive an SMS or delivery receipt0x00000005
deliver_sm_respResponse to deliver_sm_resp0x80000005
unbindClose bind response0x00000006
unbind_respResponse to unbind0x80000006
bind_transceiverBind as ‘Transceiver’0x00000009
bind_transceiver_respResponse to bind_transceiver0x80000009
enquire_linkCheck link status0x00000015
enquire_link_respResponse to enquire_link0x80000015

Note that any command in the SMPP specification which is not listed above is not currently supported.

Command States

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

CommandRequired state
bind_transmitterOPEN
bind_transmitter_respOPEN
bind_receiverOPEN
bind_receiver_respOPEN
bind_transceiverOPEN
bind_transceiver_respOPEN
unbindBOUND_TX, BOUND_RX, BOUND_TRX
unbind_respBOUND_TX, BOUND_RX, BOUND_TRX
submit_smBOUND_TX, BOUND_TRX
submit_sm_respBOUND_TX, BOUND_TRX
deliver_smBOUND_RX, BOUND_TRX
deliver_sm_respBOUND_RX, BOUND_TRX
enquire_linkBOUND_TX, BOUND_RX, BOUND_TRX
enquire_link_respBOUND_TX, BOUND_RX, BOUND_TRX
generic_nackBOUND_TX, BOUND_RX, BOUND_TRX

NB: data_sm, query_sm, cancel_sm, replace_sm and submit_sm_multi are not 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 was not 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:

CodeDescription
DELIVRDMessage delivered to destination
ACCEPTDMessage is in accepted state
EXPIREDMessage validity period has expired
DELETEDMessage has been deleted
UNDELIVMessage is undelivered
UNKNOWNMessage is in unknown state
REJECTDMessage is in rejected state
ENROUTEMessage is in ENROUTE state

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:

HexDecimalError NameDescriptionDurationError FromRelating To
00No ErrorThe message delivered successfullyPermanentMSCMobile Handset
11Unknown SubscriberThe MSISDN is inactive or no longer active.PermanentHLRDestination Network
22Unknown Subscriber -npdbMismatchFault in Number Portability Database or HLR of MSISDN range holder. Occurs more frequently if number ported more than once in certain countries.PermanentMSCDestination Network
55Unidentified SubscriberOccurs when the MSC that a message has been sent to is not aware of the subscriber IMSI. Suggests HLR has not been updated or MSC malfunction.TemporaryMSCDestination Network
66UnknownIt cannot be determined whether this message has been delivered or has failed due to lack of final delivery state information from the carrier.PermanentMSCDestination Network
99Illegal SubscriberRejection due to failed authentication or filtering.TemporaryMSCDestination Network
A10No Translation for AddressDestination number is not a valid mobile number or its routing cannot be determined.PermanentTRANSPORTSignalling
B11Teleservice Not ProvisionedRejection due to subscription not supporting SMS.PermanentHLRMobile Handset/Destination Network
C12Illegal EquiptmentRejection due to subscription, handset or network not supporting SMS.TemporaryMSCMobile Handset/Destination Network
D13Call BarredRejection due to subscription or network not allowing SMS.TemporaryHLRMobile Handset/Destination Network
1521Facility Not SupportedRejection due to subscription not supporting SMS.TemporaryMSCDestination Network
1B27Absent SubscriberSubscriber handset is not logged onto the network due to it being turned off or out of coverage. Likely to have been unavailable for 12 hours or more.TemporaryHLRMobile Handset
1C28Absent subscriber no-pageresponseSubscriber handset is not reachable on the network due to it being turned off or out of coverage. Likely to have very recently become unavailable.TemporaryMSCMobile Handset
1D29Absent subscriber IMSI-detachedSubscriber handset is not reachable on the network due to it being turned off or out of coverage. Likely to have been unavailable for several hours.TemporaryMSCMobile Handset
1E30Controlling MSC FailureThe MSC that the subscriber is currently registered to is experiencing a fault.TemporaryMSCDestination Network
1F31Subscriber Busy For MT-SMMSC is busy handling an exisiting transaction with the handset. The subscriber could be currently receiving an SMS at exactly the same time.TemporaryMSCMobile Handset
2032Equipment notSMEquippedRecieving handset or equipment does not support SMS or an SMS feature. This is temporary because the subscriber could switch to a different device.TemporaryMSCMobile Handset
2133Memory Capacity ExceededRejection due to subscriber handset not having the memory capacity to recieve the message. Likely to have been in state for 12 hours or more.TemporaryHLRDestination Network
2234System FailureRejection due to SS7 protocol or network failure.TemporaryMSCDestination Network
2335Data MissingRejection due to subscriber network decoding error or signalling fault.TemporaryMSCDestination Network
2436Unexpected Data ValueRejection due to subscriber network decoding error or signalling fault.TemporaryMSCDestination Network
2537System FailureRejection due to SS7 protocol or network failure.TemporaryHLRDestination Network
2638Data MissingRejection due to subscriber network decoding error or signaling fault.TemporaryHLRDestination Network
2739Unexpected Data ValueRejection due to subscriber network decoding error or signaling fault.TemporaryHLRDestination Network
2840Memory capacity ExceededRejection due to subscriber handset not having the memory capacity to receive the message. Likely to have run out of capacity recently.TemporaryMSCDestination Network
4569Generic delivery failureGeneric delivery failurePermanentMSCDestination Network
8C140SS7 Communication ErrorInternal SMSC error due to invalid message syntax.TemporarySMSCMessage Construction
A0160Absent subscriber IMSI-detachedInternal SMSC error caused by SS7 link/dialogue fault.TemporarySMSCDestination Network/Signalling
C8200Unable to decode responseSMSC cannot decode the response received from destination network due to an encoding or protocol fault.TemporarySMSCDestination Network/Signalling
C9201Provider AbortSubscriber network or signalling partner has terminated the signalling connection, preventing message transmission.TemporaryTRANSPORTDestination Network/Signalling
CA202User AbortSubscriber network or signalling partner has rejected the signalling connection, preventing message transmission.TemporaryTRANSPORTDestination Network/Signalling
CB203TimeoutSubscriber network not recieving packets from SMSC, or not responding to them. Alternatively, a 3rd party signalling partner may not be routing correctly.TemporaryTRANSPORTDestination Network/Signalling
CD205Timeout-PABSubscriber network or signalling partner has not responded to signalling connection setup or maintenance packets.TemporaryTRANSPORTDestination Network/Signalling
CE206RejectedSubscriber network refuses signalling connection or message packet.PermanentTRANSPORTDestination Network
CF207Local CancelSignalling with destination network has been prevented by SMSC partner or signalling partner.PermanentCARRIERSMSC Partner Routing/Signalling
12C300Screening or BlockingSMSC partner or 3rd party signalling partner has prevented messages being sent to this MSISDN or destination network.PermanentCARRIERSMSC Partner Routing/Signalling
12D301Carrier Syntax ErrorSMSC partner has rejected the message due to an unacceptable message parameter.PermanentCARRIERSMSC Partner Platform/Message Construction
12E302Carrier Internal ErrorSMSC partner could not process this message due to a platform fault, but it will be retired.TemporaryCARRIERSMSC Partner Platform
12F303Carrier Internal ErrorSMSC partner could not process this message due to a platform fault and it will not be retried.PermanentCARRIERSMSC Partner Platform
130304Carrier Routing ErrorSMSC partner cannot route this message currently, but it will be retried.TemporaryCARRIERSMSC Partner Platform/Signalling
131305Carrier Routing ErrorSMSC partner cannot route this message and it will not be retried.PermanentCARRIERSMSC Partner Platform/Signalling
3E7999CongestionSS7 signalling link at destination network, SMSC, or 3rd party signalling partner is overloaded.TemporaryTRANSPORTDestination Network/Signalling

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.

Edit on GitHub

Updated 2 months ago


Cloud SMPP


Our Cloud SMPP service is available to you immediately after creating an account on our site. It uses the same core platform and backend connections as our Enterprise SMPP service.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.