SMPP Integration

Important: The information and contents displayed in these pages is for the OpenMarket's legacy UK SMS APIs. This information is relevant if only you're still using these APIs. For information on migrating from these APIs, see the API Release Notes. Please note, however, that Reporting is still done through Partner Centre, located here: https://partner.mxtelecom.com/home.

The legacy UK SMPP interface supports a subset of the SMS Forum's SMPP v3.4 specification. It is backwards compatible with Logica's SMPP v3.3. It also supports multiple binds for redundancy and load-balancing.

The following PDUs are supported:

  • BIND_TRANSMITTER
  • BIND_RECEIVER
  • BIND_TRANSCEIVER
  • UNBIND
  • SUBMIT_SM
  • ENQUIRE_LINK
  • DELIVER_SM (initiated by OpenMarket)

OpenMarket will respond with a GENERIC_NACK reply to any other PDUs.

Binding with the SMPP interface

The SMPP interface is as similar as possible to the Logica Telepath implementation, with additional TLVs that provide:

  • Identification of yourself, the mobile operator, and the SMS
  • Extended delivery report information
  • The ability to add note and subaccount information
  • Age verification information from the mobile operator

Our inactivity timeout for this interface is set at five minutes. It is recommended that SMPP clients send ENQUIRE_LINK every minute.

We also recommend binding as transceiver rather than transmitter and receiver if possible.

If the additional TLVs do not distinguish your messaging enough, or you require more messaging throughput, you can use multiple binds to the SMPP interface. Binds can be per mobile operator if required.

Note that for your system to OpenMarket TLVs which have a value specified to be of type C-Octet String, terminating the string with a null byte is optional. We recommend adding the null byte; however, if it is missing the parameter should still be passed correctly by OpenMarket.

For OpenMarket to your system TLVs which have a value specified to be of type C-Octet String, OpenMarket will always add the terminating null byte.

Supported character sets/encodings

data_coding value

Character set

0

Modified Latin-9

1

GSM 03.38

4

8-bit binary

8

UCS2

F7

GSM 03.38 class 3

The default is Modified Latin-9.

SMPP v3.4 TLV Parameters

The SMPP v3.4 TLV parameters are detailed below.

TLVs for mobile originated (MO) messages

AV Status

This optional parameter is passed if Age Verification is enabled for MO messages to a particular short code.

  • ID: 0x3050
  • Name: AV Status
  • Direction: OpenMarket -> your system
  • Length: 2
  • Value: 0 if Age verification failed; 1 if it passed. Other values are reserved and should be ignored.

Message ID

This is an optional parameter that can be included with MO messages. It is the SMS ID used to uniquely identify an SMS message as it passes through our systems. It is a positive 64 bit integer that, when sent as a Message ID value, is formatted into a decimal and passed as a string. In our billing records, the SMS ID appears against the message.

  • ID: 0x3040
  • Name: Message ID
  • Direction: OpenMarket -> your system
  • Length: Variable
  • Value: String (not null terminated).

Operator code

This signifies which operator the originating mobile number belongs to for MO messages, rather than relying on one pipe per operator.

  • ID: 0x3010
  • Name: Operator code
  • Direction: OpenMarket -> your system
  • Length: Variable
  • Value: String (not null terminated).

TLVs for mobile terminated (MT) messages

MT Username

This TLV, used for MT messages, encompasses the destination operator for the message, the tariff and any other information that might be relevant (age verification requirements, subscription status etc).

  • ID: 0x3000
  • Name: MT Username
  • Direction: your system -> OpenMarket
  • Length: Variable
  • Value: C-Octet String

Note

This TLV allows you to specify a "note" for the message that is stored in the billing record. This has no effect on the delivery of the message but can be used as opaque data.

  • ID: 0x3031
  • Name: Note
  • Direction: your system -> OpenMarket
  • Length: Variable 1-160 bytes + optional null byte
  • Value: C-Octet String

Subaccount

This TLV allows you to specify the sub-account to be stored in the transaction log. The legacy Partner Centre can provide reporting based on this field. Sub-accounts do not need to be preconfigured.

  • ID: 0x3030
  • Name: Subaccount
  • Direction: your system -> OpenMarket
  • Length: Variable 1-30 bytes + optional null byte
  • Value: C-Octet String

TLVs for delivery reports

receipted_message_id

The receipted_message_id is a standard SMPP TLV parameter passed in delivery reports. This is the SMS ID used to uniquely identify an SMS message as it passes through our systems. It is a positive 64 bit integer that, when sent as a receipted_message_id value, is formatted as a hexadecimal number and null terminated. The SMS ID in the delivery report will match the ID returned by OpenMarket when the message was originally submitted.

  • ID: 0x001E
  • Name: receipted_message_id
  • Direction: OpenMarket -> your system
  • Length: Variable
  • Value: C-Octet String

Report reason

This is an extension of the delivery report status; the information that is available varies from operator to operator.

  • ID: 0x3020
  • Name: Report reason
  • Direction: OpenMarket -> your system
  • Length: 4 bytes
  • Value: Unsigned 32-bit Integer, see Delivery Reports.