MX Telecom SMS Gateway SMPP Interface - Details

Overview

OpenMarket now offers a RESTful and feature-rich Global SMS API. Compared to the existing MX Telecom APIs, the Global SMS API provides:

  • Automated originator selection, which selects the correct short code or VMN for any country or territory
  • Our highest level SLA and increased messaging capacity
  • Better security through Basic authentication
  • A test environment for new and migrating customers

as well as a host of other benefits. While we will continue to support our existing SMS APIs, we believe that our Global SMS API offers some exciting features and benefits that you'll want to take advantage of, and future feature development will be focused on the Global SMS API. For more information, see the Release Note on our Docs and Resources website.

Note that currently the Global SMS API does not support Premium Rate messaging. Existing Premium Rate customers should continue to use the MX Telecom APIs.

The MX Telecom SMPP interface supports a subset of the SMS Forum's SMPP v3.4 Specification. 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 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).

  • 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.

  • Managed Consent Type - when used in an AT&T ACM request (US only)
    • ID: 0x3090
      Name: Managed Consent Type
      Direction: Partner -> MX
      Length: Variable
      Value: C-Octet String

    This TLV identifies the request as an AT&T ACM request. This parameter is required for any request sent as part of the AT&T ACM workflow. Note that this parameter is also used in Verizon consent management requests (see below).

    Valid values are:

    ValueDescription
    MOInitiates a without-PIN opt in and identifies that the end user begun opt-in via an MO SMS message.
    WEBInitiates a without-PIN opt in and identifies that the end user begun opt-in via a website.
    PINAOCSIPInitiates a with-PIN opt in and identifies that it is for a single-item purchase.
    PINAOCSUBInitiates a with-PIN opt in and identifies that it is for a subscription service.
    PINIdentifies this request as the second message required for the with-PIN workflow. The request must also include the pin parameter.
    IVRAvailable only to partners who are already running AT&T ACM with IVR opt-in. This initiates a without-PIN opt in and identifies that the end user begun opt-in via an IVR service.

    For a guide on understanding and implementing ACM, see AT&T Consent Management.

  • Pin (AT&T US services only)
    • ID: 0x3091
      Name: Pin
      Direction: Partner -> MX
      Length: Variable
      Value: C-Octet String

    The PIN entered by the end user as part of the AT&T ACM with-PIN opt in process.

    For a guide on understanding and implementing ACM, see AT&T Consent Management.

  • Managed Consent Type - when used in a Verizon consent management request (US only)
    • ID: 0x3090
      Name: Managed Consent Type
      Direction: Partner -> MX
      Length: Variable
      Value: C-Octet String

    This TLV identifies the request as a Verizon consent management request and identifies how the end user initiated opt-in. Note that this parameter is also used in AT&T ACM requests (see above).

    Valid values are:

    ValueDescription
    IVRThe end user initiated opt-in via an IVR service.
    MOThe end user initiated opt-in via an MO SMS message.  
    WEBThe end user initiated opt-in via a website.

    For a guide on understanding and implementing Verizon consent management, see Verizon Consent Management.

  • Initial optin keyword (Verizon US services only)
    • ID: 0x3092
      Name: initial_optin_keyword
      Direction: Partner -> MX
      Length: Variable
      Value: C-Octet String

    The keyword the end user entered (via SMS) that triggered the specific service. If the opt-in occurred via a web page, you may send any keyword. The maximum length is 20 characters.

    The initial opt-in keyword parameter is not required for IVR initiated single item and subscription purchases.

    For a guide on understanding and implementing Verizon consent management, see Verizon Consent Management.

    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@uk.openmarket.com.