Europe USA/Canada

MX Telecom SMS Gateway SMPP Interface - Details

Overview

The MX Telecom SMPP interface supports a subset of the SMS Forum's SMPP v3.4 Specification (http://smsforum.net). It is backwards compatible with Logica's SMPP v3.3.

Supported SMPP versions and PDUs

The SMPP interface supports a subset of the SMS Forum's SMPP v3.4 specification, and is backward compatible with Logica's Telepath implementation of 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 MX Telecom)

The SMS Gateway 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 carrier, and the SMS
  • Extended delivery report information
  • The ability to add note and subaccount information
  • Age verification information from the carrier

The SMS Gateway's inactivity timeout 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 carrier if required.

Note that for Partner -> MX 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 the SMS Gateway.

For MX -> Partner TLVs which have a value specified to be of type C-Octet String, the SMS Gateway will always add the terminating null byte.

Supported characters

data_coding valueCharacter set
0Modified Latin-9
1GSM 03.38
48-bit binary
8UCS2
F7GSM 03.38 class 3

The default character set is Modified Latin-9.

See our FAQ for a description of the Modified Latin-9 and GSM 03.38 character sets.

SMPP v3.4 TLV Parameters

The SMPP v3.4 TLV parameters are detailed below.

TLVs for mobile originated (MO) messages

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

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

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

    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 the SMS Gateway. 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.

  • Operator code
      • ID: 0x3010
      Name: Operator code
      Direction: MX -> Partner
      Length: Variable
      Value: String (not null terminated). See Network Codes.

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

    TLVs for mobile terminated (MT) messages

  • MT Username
      • ID: 0x3000
      Name: MT Username
      Direction: Partner -> MX
      Length: Variable
      Value: C-Octet String.

    This parameter, 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).

  • Note
      • ID: 0x3031
      Name: Note
      Direction: Partner -> MX
      Length: Variable 1-160 bytes + optional null byte
      Value: C-Octet String.

    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.

  • Subaccount
      • ID: 0x3030
      Name: Subaccount
      Direction: Partner -> MX
      Length: Variable 1-30 bytes + optional null byte
      Value: C-Octet String.

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

  • Purpose Code (US services only)
      • ID: 0x3070
      Name: Purpose code
      Direction: Partner -> MX
      Length: Variable
      Value: String (see below)

    Verizon requires you to identify the purpose of some standard rate messages sent as part of a premium rate campaign. The possible values are:

    ValueDescription
    opt_in_premium Use for standard rate messages sent during the opt-in process.
    premium_content Use when delivering purchased premium content in a standard rate message.

  • Optin1 (T-Mobile US services only)

    • This TLV is required by T-Mobile in the United States only.

      ID: 0x3060
      Name: Optin1
      Direction: Partner -> MX
      Length: Variable
      Value: C-Octet string

    This TLV describes how the first opt-in occurred. It takes the format source:sourceid, where both source and sourceid are mandatory.

    It is required for premium rate messages on services that require double or single opt-in.

    ValueDescription
    sms:smsid The SMS ID returned by the SMS Gateway that corresponds to the first mobile originated (MO) SMS opt-in message.
    For example: sms:123455678
    url:website The URL where a web opt-in occurred.
    For example: url:http://example.com
    other:text Description of any other opt-in scenario.
    For example: other:at+point+of+sale

  • Optin1TS (T-Mobile US services only)

    • This TLV is required by T-Mobile in the United States only.

      ID: 0x3061
      Name: Optin1TS
      Direction: Partner -> MX
      Length: 4
      Value: unsigned 32-bit integer

    This TLV specifies the time that the first opt-in occurred. This timestamp is in seconds since 01/01/1970 (also known as a Unix timestamp). For example, the 5th September 2010 at 07:30:00 is: 1283689800. You do not need to specify this parameter if the end user's first opt in was through an SMS message, i.e., where the value of Optin1 is sms:smsid.

  • Optin2 (T-Mobile US services only)

    • This TLV is required by T-Mobile in the United States only.

      ID: 0x3062
      Name: Optin2
      Direction: Partner -> MX
      Length: Variable
      Value: C-Octet string

    This TLV describes how the second opt-in occurred. It takes the format source:sourceid, where both source and sourceid are mandatory.

    It is required for premium rate messages on services that require double opt-in.

    ValueDescription
    sms:smsid The SMS ID returned by the SMS Gateway that corresponds to the second mobile originated (MO) SMS opt-in message.
    For example: sms:123455678
    url:website The URL where a web opt-in occurred.
    For example: url:http://example.com
    other:text Description of any other opt-in scenario.
    For example: other:at+point+of+sale
    pin:text PIN used for PIN opt-in services.
    For example: optin2=pin:1337

  • Optin2TS (T-Mobile US services only)

    • This TLV is required by T-Mobile in the United States only.

      ID: 0x3063
      Name: Optin2TS
      Direction: Partner -> MX
      Length: 4
      Value: unsigned 32-bit integer

    This TLV specifies the time that the second opt-in occurred. This timestamp is in seconds since 01/01/1970 (also known as a Unix timestamp). For example, the 5th September 2010 at 07:30:00 is: 1283689800.

    You do not need to specify this parameter if the end user's second opt in was through an SMS message, i.e., where the value of Optin2 is sms:smsid.

    TLVs for delivery reports

  • receipted_message_id
      • ID: 0x001E
      Name: receipted_message_id
      Direction: MX -> Partner
      Length: Variable
      Value: C-Octet String.

    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 the SMS Gateway. 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 the SMS Gateway when the message was originally submitted.

  • Report reason
      • ID: 0x3020
      Name: Report reason
      Direction: MX -> Partner
      Length: 4 bytes
      Value: Unsigned 32bit Integer, as defined on the Delivery Report Reasons page.

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

    Account Setup

    Please contact us for further information.

    For more information, please contact us at 1-877-698-3532 or via email at sales@mxtelecom.com.

    © 2000-2012 MX Telecom Inc