Things to Know

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

• How we set up your accounts
• Account configuration and OpenMarket SMPP settings
• Throttle rate
• Concurrent sessions
• Data Coding Scheme
• Using message originators
• Automated Originator Selection
• When and how messages are retried
• Custom TLVs
• Testing your integration
• Single and multipart messages
• MO and Delivery Receipt flow control windowing

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.

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

OpenMarket SMPP settings.

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

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, 10DLCs, 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.

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:

• submit_sm
• deliver_sm

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.

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.

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.