Things to Know

Before you start using SMPP, familiarize yourself with these features:

How we set up your accounts

When you sign on with OpenMarket, your account manager will work with you to make several decisions:

  • Which OpenMarket product(s) you intend to use
  • Whether you're sending messages within or outside your country or territory
  • Whether you're sending one-way or two-way messages
  • Whether you're using HTTP, SMPP, or both
  • What type(s) of originators you're using (short codes, VMNs, etc.)

When we set up your OpenMarket account, we'll provide you with the user and application accounts that you need with access to the products you're licensed to use. We set permissions on each account to ensure it accesses only the resources it needs. Accounts for applications are normally numbers, while accounts for people are normally a business email address. The following tables provides examples.

Account ID / Name

Description

123-456-789-12345

An ID specifically enabled for SMS messaging.

Used in any SMPP request, such as sending an MT message to any end user.

matthew@example.com

For this example, Matthew is a user in the Finance department. This account format enables Matthew to access Customer Center tools and reporting. OpenMarket Support will recognize Matthew when he emails using this address.

As Matthew is in Finance, he is able to see all reports including financial reports.

Jinghua@example.com

For this example, Jingua is a user in the development organization. This account enables Jinghua to access Customer Center tools and reporting. OpenMarket Support will recognize Jinghua when she emails using this address.

As Jinghua is in development, she is restricted from seeing Financial reports.

Your credentials for using OpenMarket operations and applications are provisioned by OpenMarket's Identity Service and configured with individual permissions. When one of our operations or applications receives a request, it checks to make sure that the authentication credentials are valid and that the corresponding user has the required permissions to make that API call.

Note: If you're using MEP you will be able to create and administer your own application account when authenticating with OpenMarket.

Account configuration and OpenMarket SMPP settings

SMPP authentication is performed when an SMPP bind request operation is initiated connecting you to OpenMarket. Once the Bind response is returned, the request is authenticated and the connection established. If an error is encountered during the request, the response will contain a response code with the reason.

Account configuration settings

Configuration Setting

Values

How to use

SMSC Host

smppgw.openmarket.com

This is the host to use when establishing SMPP binds to OpenMarket. Always use the fully qualified domain name. Your service should honor the time-to-live specified in the DNS resolution for the fully qualified domain name. OpenMarket supports transmitter, receiver, and transceiver binds.

SMSC Port

8143: Secure socket. Transport Layer Security (TLS) versions 1.2 and 1.1 are supported

8143 is the host port to use when establishing secure SMPP binds to OpenMarket. We support transmitter, receiver, and transceiver binds. You must use TLS with port 8143.

SMPP Version

3.4

This is the interface_version value to use in the bind PDU operation. Use SMPP version 3.4.

System ID

Your OpenMarket SMPP account ID.

This is the system_id value to use in the bind PDU operation. This can only be your OpenMarket SMPP application account ID without the dashes. For example, OpenMarket SMPP application account ID: 123-456-789-12345, or OpenMarket SMPP application account ID transformed to system_id format: 12345678912345

Password

The valid password for your SMPP account.

This is the password value to use in the bind PDU operation. Use the valid password for your OpenMarket SMPP application account. The password can be up to 100 characters, but only if your system supports that number. Otherwise, the maximum password length is eight characters.

System Type

Not required for the bind PDU operation.

For more information, see the SMPP Protocol Specification v3.4.

Source IP Address Range

The source IP addresses from which you will send SMPP PDUs.

When you are configuring your account with OpenMarket ensure you send the source IP address your application will be using for SMPP. You will not be able to establish an SMPP bind unless OpenMarket whitelists your source IP addresses. If you plan to change your source IP addresses at a later time, please notify OpenMarket Support.

OpenMarket SMPP settings.

Configuration Setting

Values

How to use

Character set used for all MOs and for MTs where the Data Coding Scheme is set to zero (DCS 0)

Choose a default of either:

  • ISO-8859-1 (Latin-1)
  • GSM 7-bit default alphabet with the extension table of 3GPP TS 23.038 / GSM 03.38.

This determines the character set used for all SMPP deliver PDUs.

OpenMarket also assumes that this is the character set of your submit PDUs unless the request specifies a different character set or encoding.

For more information, see Data Coding Scheme.

Throttle Rate

10 (default)

The maximum number of MT submits you can send per second. This value is tailored to your account, based on your use cases and agreement with OpenMarket.

For more information, see Throttle rate below.

Connection Timeout

30000 milliseconds (30 seconds)

OpenMarket recommends your system sends enquire_link PDUs every 20 seconds if your application is not actively submitting messages.

For more information, see Connection timeout below.

Number of allowed concurrent sessions

2 (default)

The total number of concurrent SMPP binds allowed for your account. This value is tailored to your account, based on your use cases and agreement with OpenMarket. See Concurrent sessions below.

Throttle rate

The OpenMarket Service Level Agreement (SLA) may restrict the number of messages you can submit based on the maximum allowed message submits per second for your account. This is known as transaction throttling. If the permitted limit is reached, OpenMarket may reject subsequent transactions with SMPP error 0x058 (throttle rate exceeded).

The default throttle rate is stated in your contract. For questions regarding your configured throttle rate, or to request a modification to your contractual limit, contact your OpenMarket account manager.

Connection timeout

After you establish a connection and acknowledge an authenticated bind request, you can send additional requests or responses. A response is issued for each request. The network connection into the SMSC ends when the idle connection time, in milliseconds (ms), is exceeded.

Idle time is when no SMPP commands are sent or received across an open network connection within the connection timeout period. The connection is dropped as a result, and you must re-establish it. To avoid this situation, send an enquire_link operation across the appropriate virtual connection to keep the connection alive. You can set the enquire_link operation over both the bind_transmitter and bind_receiver sessions. Your application should send the enquire_link before the connection timeout occurs.

OpenMarket expects to receive an enquire_link operation on each of your SMPP sessions at least once every 30 seconds and will terminate the SMPP session if this operation is not received within that period. To avoid bind termination as a result of connection timeout, OpenMarket recommends that your SMPP sessions trigger an enquire_link operation every 20000 milliseconds

Concurrent sessions

You can bind the maximum concurrent number of sessions at any given time. The default setting for a SMPP account is to have a maximum of two (2) concurrent sessions. This means you will be able to have either two transceiver-type binds, two pairs of a receiver and transmitter-type binds, or a combination of the two.

To increase the maximum number of concurrent SMPP sessions allowed for your account, contact your account manager.

Data Coding Scheme

In SMPP, the data coding scheme (DCS) indicates information that includes (but isn't restricted to) the character set that the message text is in.

Default character set

When your account is first provisioned, we set a default character encoding on your account for both sending and receiving messages. When sending messages, use DCS 0 to indicate that the message text uses your default character encoding. You can choose either of these two character sets as the default for your account:

  • GSM 7-bit default alphabet and extension table of 3GPP TS 23.038 / GSM 03.38.

    A table of characters is below.
  • Latin 1 (ISO-8859-1).

    A table of characters is below.

During the provisioning process with OpenMarket, make sure to inform us as to whether you want to have GSM or Latin-1 as your default character set; otherwise, Latin-1 is set as your default.

Important: If at a later date you want to change the default character set, contact OpenMarket Support or your account manager. Changing the encoding you are using for DCS 0 without coordinating with OpenMarket might result in your message text becoming corrupted.

Other DCS options

Other DCS options include:

  • DCS 3 — Latin 1
  • DCS 4 — Binary message
  • DCS 8 — UTF-16 big-endian encoding. See the Wikipedia article: http://en.wikipedia.org/wiki/UTF-16.
  • DCS 240 — Flash (class 0) message. The message text must use the default character set configured for your account.
  • DCS 24 — Flash (class 0) message, where the message text uses UCS-2.
  • DCS 246 — SIM-specific binary message. This is only used in special cases where you are communicating with a custom application on the mobile device. No message reaches the phone's SMS inbox.

GSM character set

See also the Wikipedia article for more information: http://en.wikipedia.org/wiki/GSM_03.38.

Modified Latin-9 character set

This character set is based on ISO-8859-15 (Latin-9). However, in order to fully cover the GSM character set and also has different characters at 0xA8, 0xA4, 0xA6, 0xB4, 0xB8, 0xBC, 0xBD, 0xBE. The characters not present in the GSM character set are shown on a grey background in the table below.

The acronyms in the table are:

  • LF — line feed
  • FF — form feed
  • CR — carriage return
  • SP — space
  • NBSP — non-breaking space
  • SHY — soft hyphen

See this Wikipedia article for more information about the Modified Latin-9 character set: https://en.wikipedia.org/wiki/ISO/IEC_8859-15.

Using message originators

Sending SMS messages always requires using a message originator (see also Message originators). When you're sending messages globally, you will likely use multiple message originators for the different target countries and mobile operators. Because it can be challenging to select the correct message originators for all of your end user numbers, the Global SMS API gives you a way to transfer the work to OpenMarket using Automated Originator Selection. By providing us with your target regions and the originators you want to use, our system can select the right originator for each message.

As an example, the following table shows the information you need to provide us if you wanted to send messages in the US, UK, New Zealand, and Australia.

Region

Interaction

Message Originator

US

Not applicable because all messages in US and Canada are considered two-way

Short code: 222111

UK

Global two-way (send and receive)

Short code: 58870

New Zealand

Global one-way (send only)

Alphanumeric string: KIWI321

Australia

Global one-way (send only)

Alphanumeric string: AUSSIE123

For a list of country coverage, and the types of supported originators, see Coverage Maps.

Content of the message request

In any request to send a message, you must always specify a destination address—the end user's phone number—in an international format. If you only have one message originator for each region, this is all we'll need to know. For MTs, the source address is a required parameter. This is the phone number or alphanumeric string that identifies you as the message sender. This is the message originator. If you have multiple of the same type of originator for a region—for example, two US short codes, then you must include source address in the request so that we know which originator to use. However, if you pass NULL as a value for the source address, and you're using multiple originators in a region, you might need to specify the following custom TLV parameter:

  • interaction — Identifies whether you want to use a number to which end users can respond.
    • For one-way messaging—when you do not need end users to respond to the message—suitable message originators are alphanumeric strings and virtual mobile numbers (VMNs).
    • For two-way messaging—when you want end users to be able to respond—you need to use a short code, VMN, toll-free number or landline number that has been provisioned with the appropriate mobile operators. Note that, in the US and Canada, all message originators are two-way.

If you specify source address, OpenMarket will determine the interaction based on the source address TON and your global account settings. However, if your account is set up for global one-way SMS only, then any source address in the MT will be assigned a one-way interaction, regardless of the source address TON.

For more information on the use of OpenMarket custom TLVs, see submit_sm OpenMarket custom TLVs.

Note: Regardless of the value of interaction, any number provisioned to receive MOs will always be able to receive messages. The interaction only determines the preferred originator to use if you don't provide it in the request.

Automated Originator Selection

Automated Originator Selection is implemented automatically on your application account when your account is provisioned. You will need to provide us the end user's number (the destination address in the message request). We determine the country of the end user first and then use the matching originator. If you have multiple message originators for the same region, we may need more information in order to choose the correct originator for a particular end user.

  • For one-way messaging, you need to provide a list of the countries you want to message, and which originator(s) to use. You can use the same originator globally, or use different originators for different regions. In most regions, you will not need to provision these numbers and alphanumeric strings with the mobile operators.
  • For two-way messaging, you need to provide us with the numbers provisioned in that region. OpenMarket can work with you to provision short codes, VMNs, and other types of numbers with mobile operators.

Note that in the US and Canada, all messaging is two-way.

If you attempt to send a message without a source address, and the SMS service cannot find an applicable source address associated with your account using Automated Originator Selection, a mobile-terminated message can then fail with one of two delivery receipt error codes:

  • 593: Cannot determine which message originator to use
  • 597: Account has no provisioned address that can reach destination

How we choose message originators

When choosing which message originator to use, the OpenMarket system considers:

  • The content of your message request
  • Rules around the use of originators [short codes, virtual mobile numbers (VMNs), toll-free numbers, and landline numbers]

Rules followed to determine a message originator

OpenMarket follows these rules:

  • We will choose a national (local) originator whenever possible over an originator from another country.
  • If you specify an interaction that isn't available for your account in a specific region, then we reject the message.
  • We will reject the message if the type of interaction and the source address conflict. For example, we would reject a message if its source address was "ACME" (an alphanumeric string) but the interaction was set to two-way. Therefore, only set what you need in the request.

The following examples illustrate what values to include in a message request. As you can see, you include source address or interaction type only if you need to differentiate between two similar originators that are provisioned in the same region.

Example

Description

Provisioned message originators:

  • 98765, short code, UK
  • 3312303120, VMN,France
  • 66655, short code, US

In this example, if any message request is sent to a UK, French or US end user, then OpenMarket SMS will send the message using the message originator for that region. You would not need to include source address or interaction in the request.

Provisioned message originators:

  • 654321, short code, Puerto Rico
  • 442089878855, VMN, Global (note, this is a UK number)
  • 18772772801, toll-free, US and Puerto Rico

In this example, it is possible for all the message originators to reach Puerto Rico end users.

However, OpenMarket would choose the Puerto Rico short code by default, as a local short code takes precedence over a UK number (even if it is global) and a North American toll-free number.

You would not need to include source address or interaction in the request, unless you wanted the message to use a different originator.

Provisioned message originators:

  • MYBRAND, alphanumeric string, India
  • 34911062005, VMN, Spain
  • 420736370463, VMN, Czech Republic

In this example, if any message is sent to Spain, India, and the Czech Republic, then OpenMarket will use the provisioned message originator. You would not need to include source address or interaction in the request.

However, if you send the MT with a value of two-way for interaction:

  • Messages sent to Spain end users are accepted.
  • Messages sent to Czech Republic end users are accepted.
  • Messages sent to India end users are rejected. The message originator for India is not two-way, and there is no other number provisioned for India.

Provisioned message originators:

  • 12345, short code, France
  • 45678, short code, France

In this example, if a message is sent to a French end user, then the message request must include a source address. This is because there is no way for OpenMarket to determine which of the short codes you would prefer us to use.

If the request doesn't include source address, then OpenMarket responds with status code 593, “Cannot determine which message originator to use”.

When and how messages are retried

OpenMarket can, on your behalf, retry MTs that fail with retryable error conditions. Automatic retry applies to MTs that fail with retryable error conditions after the MT is accepted by OpenMarket and a ticket ID is returned to your system. We can retry MTs for up to 24 hours or until the MT validity period expires, whichever comes first. OpenMarket returns a delivery receipt, if requested, after the maximum number of retries has been exhausted.

If you submit an MT with a carrier ID and the MT is rejected by the carrier with an invalid destination address error, OpenMarket will perform a carrier lookup to determine if a different carrier ID should be used to route the MT. If a different carrier ID for the destination address is found, OpenMarket will submit the MT to the new carrier and your account will be charged for the lookup.

When OpenMarket is retrying an MT, the message state is “Retrying” in the SMS Activity Search results on Customer Center.

By default, automatic retry is enabled on accounts for new customers. If you would like to disable or re-enable automatic retry on an existing account, contact your OpenMarket account manager.

Custom TLVs

Custom TLVs are optional when using any of the operations. Even without using custom TLVs you'll still have access to core functionality. TLVs can be enabled when you provision your account or later by contacting your account representative.

TLVs are supported in these operations:

Testing your integration

OpenMarket provides a Customer Integration Environment (CIE) for testing your integration. All responses to the request are simulated by OpenMarket, so neither the mobile operators nor end users are sent actual SMS messages.

Connecting to the CIE

Use the following information to connect to the CIE.

  • Host: smppgw-cie.openmarket.com
  • Port: 8143

US standard rate simulations

When you submit MTs, you will receive responses for both successful and failed messages. Errors are usually caused by improperly formatted messages or invalid parameters. For example, if you submit a message with a carrier ID that OpenMarket does not support, you will receive a response specific to that error condition.

To test simulated end-to-end message delivery, including error conditions related to unsuccessful message delivery to the carrier or subscriber handset, you must use the test scenarios provided here. The CIE returns a delivery receipt if you request a delivery receipt on MT submit. The Carrier ID field indicates the supported carriers for each test case.

Operator ID 383 = AT&T

Operator ID 77 = Verizon Wireless

Operator ID 79 = T-Mobile USA

Operator ID 34 = Sprint

If you omit Operator ID in the test cases, then the CIE uses a default Operator ID of 383 (AT&T).

Test scenarios for US standard rate MT messages

You will find the response code in the delivery receipt for a test message.

Phone number

Operator ID

Response code

Response code description

14081230000

34

0

"Message sent"

Note that you should consider this a successful message delivery if you receive this receipt, as some operators do not provide further updates.

14081230000

383, 77, 79

4

"Message delivered"

14081234567

34, 77

3041

"US standard rate message blocked by the OpenMarket deactivated numbers firewall"

This code is relevant for US messaging only. It's returned if the mobile number is on a list of deactivated numbers. Your program should now take the number out of your messaging list. See Handling Deactivated Phone Numbers for more information.

14075550155

77

810

"Failed message delivery"

Single and multipart messages

Using the SMPP API, messages are not automatically split into multiple parts if the number of characters in the message is greater than what is contained within a single message. If you are not comfortable splitting a message into multiple parts, OpenMarket recommends you use the HTTP Global SMS API, which will automatically split long messages into multiple parts.

When sending a multipart message, SMPP requires you to send each message part using a separate request. Each request must include a UDH in the message text that indicates that it is part of a multipart message. The two relevant parameters in the PDU body are:

  • esm_class — set the value to 0x40 (this is 64 in decimal) to indicate that there is a UDH.
  • short_message — add the UDH information at the beginning of the message.

The UDH requires 6 bytes, which means that the number of characters you can send in each message part is reduced. The UDH required in each message part is described in this table.

Byte

Description

05

Length of the rest of the UDH. This is "5" bytes.

00

Indicates it is a multipart message.

03

Length of the subheader; e.g., the rest of the UDH. This is "3" bytes.

XX

An identifier for the specific multipart message. This can be any hexadecimal number, as long as the value is the same for all of the message parts.

In the example below, this is "44".

YY

Total number of parts in the multipart message.

In the example below, there are "03" parts in total.

ZZ

The sequence number for the message part. This ensures that the message is reconstructed on the mobile phone in the right order. The numbering begins at 1.

Example message with UDH

This example shows the short_message, including UDH, for a Shakespeare phrase that is 327 characters long. Our message is being sent to a UK number, so each part is up to 153 GSM characters. You can see that the first five bytes remain the same across all parts, while the sixth byte changes to indicate the sequence number.

Part one

0x05 0x00 0x03 0x44 0x03 0x01 I will not yield, to kiss the ground before young Malcolm's feet, and to be baited with the rabble's curse. Though Birnam wood be come to Dunsinane, and 

Part two

0x05 0x00 0x03 0x44 0x03 0x02 thou opposed, being of no woman born, yet I will try the last. Before my body I throw my warlike shield. Lay on, Macduff, and damn'd be him that first cr

Part three

0x05 0x00 0x03 0x44 0x03 0x03 ies, 'Hold, enough!'

Character length and encoding differences between regions

You'll need to adjust the message length for each part based on the maximum number of characters the local mobile operators accept. In almost all countries, each part can be up to 153 characters (using GSM) or 67 characters (using UCS-2 / UTF-16). However, there are a few countries where the maximum size is smaller, such as Canada, Chile, Brazil and Ecuador. You can find out more about the message length limits, and what character set is predominantly used in a country, in the Global Coverage section of this site.

What happens when OpenMarket receives the request?

OpenMarket will check that the message length for each part before accepting or rejecting the part. If you are using GSM, then we may re-encode the message to Latin 1, as some mobile operators only accept this encoding. In all other instances, we forward on the message to the mobile operator using the encoding in your request.

In most cases, the mobile operator will then accept (and deliver) the message. However, an operator may reject the message if you have used Latin 1 with GSM escape characters, as the byte length for the escape characters is longer than Latin 1.

MO and Delivery Receipt flow control windowing

OpenMarket limits the number of unacknowledged MOs and DRs sent on SMPP binds to your account at any point in time. Unacknowledged MOs and DRs are limited to avoid sending a higher rate of MOs and DRs to your system than can be processed. MOs and DRs are sent by OpenMarket to your system using the SMPP deliver_sm PDU. Your system acknowledges receipt of the MOs and DRs by returning a deliver_sm_resp PDU back to OpenMarket.

When a new a new account is provisioned for your OpenMarket account using SMPP, a default MO and DR flow control window of 100 unacknowledged MOs & DRs (combined) per bind is set on an OpenMarket SMPP gateway host. If there are more than 100 unacknowledged MOs and DRs combined on a given bind, additional MOs and DRs are not sent on that bind until there are less than 100 unacknowledged MOs & DRs outstanding.

OpenMarket retries sending MOs and DRs when your service does not acknowledge receipt of MOs and DRs with a deliver_sm_resp PDU within 30 seconds. OpenMarket will continue to retry sending MOs and DRs when your service sends a deliver_sm_resp PDU with an unsuccessful send command status. If you want to adjust the default number of unacknowledged MOs and DRs per bind on your account or if you want to adjust the amount of time OpenMarket waits to retry sending an MO and DR, contact your account manager or OpenMarket support so your account can be configured accordingly.

If your system does not support sending the deliver_sm_resp PDU, contact your account manager or OpenMarket support so your OpenMarket account can be configured accordingly. Otherwise, OpenMarket will retry sending MOs and DRs to your system when a deliver_sm_resp PDU is not received.