OpenMarket TLV Parameters

The SMPP 3.4 specification provides the capability to define additional SMPP parameters, which enable the definition of custom parameters specific to OpenMarket SMS requirements. These parameters are defined in tag, length, and value (TLV) format. Because protocol data units (PDUs) use a structure defined by the transaction type, any custom parameters appear at the end of the PDU, and the order does not matter.

OpenMarket supports the following custom parameters using SMPP v3.4:

  • carrier ID
  • charge type
  • note
  • program ID
  • purpose
  • receipted message ID*
  • response code
  • response code description
  • retry

*In delivery receipts (deliver_sm PDUs) this is the OpenMarket ticket ID we have assigned to the referenced MT message. We also send this TLV with MO messages to provide the OpenMarket ticket ID assigned to the MO message.

Depending on the region in which you're messaging or your use case, some of the custom OpenMarket SMPP parameters used for MT messaging are required rather than optional.

Search

Search this page for a TLV or response code:

TLVs for MT messages

The following custom TLVs exist for mobile terminated (MT) messaging. Some of these TLVs are required based on the region that you are sending to.

Program ID

Use this TLV to provide the program ID that is provisioned for your campaign. You must provide this for short code messaging in the US and Canada.

Tag

Value

0x2157

Size: variable

Constraints: maximum 50

Type: octet string

Required? Required for programs using a short code in the US and Canada. It is not required for international services or US and Canadian services using other messaging originators.

Charge type

Use this TLV to indicate whether the message type is standard rate (for US/Canada) or international (including India).

If you do not provide this TLV, then OpenMarket assumes the request is for a standard rate message to a US or Canadian mobile phone number. Therefore you must provide this for international messaging.

Tag

Value

0x2151

Size: 1

Type: byte

Valid values:

  • 0 — do not charge recipient, US and Canada standard rate SMS
  • 20 — international SMS

Required? for international SMS

Purpose

Use this TLV to classify the purpose of any MT message sent to an Indian end user as either transactional or promotional.

You must provide this when sending a message to an end user in India. See also India.

Tag

Value

0x215C

Size: 1

Type: byte

Valid values:

  • 1 — standard_content

  • 4 — opt_in_standard

  • 5 — stop_confirmation

  • 6 — help_response

  • 7 — other_administrative 

The following two values apply only to MTs sent to mobile subscribers in India:

  • 8 — transactional
  • 9 — promotional

Required? For messages sent to an end user in India. For any messages sent elsewhere this TLV is optional (ignored).

Carrier ID

Use this TLV when sending standard rate (US/Canada) messages via a short code. This TLV indicates the mobile operator you wish us to send the message to. If you do not submit carrier ID, OpenMarket can determine the destination mobile operator for you.

Do not use this TLV for international messaging or for US and Canadian messages sent via a long code, toll-free or landline number. In these cases OpenMarket uses dynamic routing to determine the mobile operator for each message.

Note that this TLV is also returned with MO messages.

Tag

Value

0x2150

Size: 2

Type: short

Valid values:A valid OpenMarket mobile operator ID. See Mobile Operator IDs for a list of valid OpenMarket mobile operator IDs.

Required? No. Use this TLV, if desired, for standard rate (US/Canada) messaging via a short code. Do not use this TLV for international messaging.

Retry

Use this TLV to include the OpenMarket ticket ID of a previously failed MT. No validation is performed other than ensuring the field is a valid length.

Tag

Value

0x2169

Size: variable

Type: octet string

Valid values:A valid MT ticket ID

Maximum: 23

Required? No

Note

This optional TLV allows you to add data to the request that you may want available in reports, such as individual identifiers (e.g. your own transaction, ticket, or system IDs). It has no effect on the message or its delivery.

This value appears in the SMS Detailed Data Source report.

Tag

Value

0x2168

Size: variable (0-200)

Constraints: maximum 200 characters, Latin-1 text string

Type: octet string

Required? No

TLVs returned with MO messages

OpenMarket sends only one custom TLV with MO messages.

Carrier ID

This TLV indicates the mobile operator associated with the mobile number the message was sent from.

Note that you can also include this TLV in MT messages (US/Canada standard rate only).

Tag

Value

0x2150

Size: 2

Type: octet string

Value: an OpenMarket operator ID

Required? Optionally returned

TLVs returned in responses and delivery receipts

OpenMarket may add the following custom TLVs to submit_sm_resp and deliver_sm PDUs. These are sent only if there is an error condition.

Response code

If present, the value of the TLV contains one of OpenMarket's response codes to indicate an error condition. This is jointly included with the response code description TLV.

For submit_sm_resp PDUs this TLV provides the most accurate information about why a message may have failed, compared to the SMPP error codes and custom OpenMarket error codes.

See the tables below for a full list of the codes returned.

Tag

Value

0x2153

Size: 2

Type: short

Value: The OpenMarket response code.

Maximum: 65536

Required? Only if an error condition occurs.

Response code description

If present, the value of the TLV contains the description of the OpenMarket response code returned. This is jointly included with the response code TLV.

Tag

Value

0x2167

Size: variable

Type: octet string

Constraints: maximum 200

Value: text description of the OpenMarket response code.

Required? Only if an error condition occurs.

Response codes for submit_sm_resp PDU

The following codes and descriptions may be returned in submit_sm_resp PDUs.

Code

Description

Notes

341

Transaction failed: Carrier ID does not exist

Verify the carrier ID used in the message submitted to OpenMarket.

Retryable: no

369

Account not permitted to use an alphanumeric source address

You have specified an alphanumeric string as your sender (source) address, rather than a short code or other number. To use an alphanumeric string, you must be provisioned in our systems first.

If you did not intend to send a string, check that you have not included any additional characters in the address.

Retryable: no

540

Invalid request - invalid value for: <description>.

Your request was malformed in some way; for example, a required element or attribute was missing or misspelled. The response message will include a description that varies depending on the issue.

For example, if your program ID was above the maximum allowed length, you would receive the message: "Invalid request - invalid value for: programId"

Retryable: no

Response codes for deliver_sm PDU

The following codes may be returned in deliver_sm PDUs.

Code

Description

Notes

351

Transaction failed: Invalid destination address value

Mobile operators send us this delivery receipt for a variety of reasons. Unfortunately, these different error conditions are mixed between ones you could retry or not, based on the operator's own use of this code.

If you are messaging anywhere outside of the US, we cannot refine the issue further, other than knowing that the message was sent using the right encoding to the correct mobile operator.

OpenMarket has received more information from the US mobile operators. When messaging a US end user, the possible reasons can be one of:

  • Any operator: The mobile number is not on the mobile operator's network.
  • Any operator: The mobile number has been deactivated. Check the Deact reports on Customer Center.
  • AT&T, T-Mobile, and MetroPCS: The phone number belongs to a prepaid user who does not have enough credit to receive an SMS.
  • T-Mobile only: The end user is not provisioned to receive SMS from all short codes (or from specific short codes).
  • T-Mobile only: The end user is on a MVNO connected via T-Mobile. T-Mobile does not deliver SMS messages from short codes to end users on MVNOs.

In general, mobile operators do not want SMS senders to retry MT messages that have failed with error code 351. However, given the range of different possible root causes, we think it is reasonable to retry some of these messages.

Here is our suggested behavior for US messaging:

  • Perform a number preview request to confirm that the number is on the mobile operator's network.
  • Check the Deact reports to ensure the number is still live
  • For T-Mobile specifically, you could retry the message using a US VMN or other number
  • If desired, retry the message using a slow retry method; for example, retrying once every day for up to 7 days

Retryable: conditional

368

Invalid source address value

Message requires a source address, verify one is provided, and is correct for the locale of the destination address.

Retryable: no

388

Binary messaging is not supported for this carrier

The mobile operator does not support WAP push or similar data transfer

Retryable: no

560

Message recipient not authorized by carrier to receive the message

Retryable: no

561

Content blocked by carrier

Retryable: no

562

Short code not active

Contact your OpenMarket account manager if you believe that you are provisioned for the operator or if you want to begin provisioning.

Retryable: no

563

Short code expired

Contact your OpenMarket account manager if you believe that you are provisioned for the operator or if you want to begin provisioning.

Retryable: no

564

Short code blocked

The mobile operator rejected the message as the short code is currently blocked from sending messages across their network.

Contact your OpenMarket account manager if you are unaware of why you have received this error.

Retryable: no

565

Reseller address blocked by carrier

The mobile operator rejected the message as the end user is connected to their network via a mobile virtual network operator (MVNO). This restriction is on short code messages.

Retryable: no

566

Destination address blocked by carrier

Retryable: no

568

Destination address not provisioned for SMS

Destination address not provisioned for SMS.

Retryable: no

569

Destination address suspended by carrier

Destination address suspended by mobile operator.

Retryable: no

570

Invalid charge amount: charge amount not allowed for charge type

You cannot include a charge amount in your request for charge type 20.

Retryable: no

571

Campaign rejected by carrier

This error applies to messages sent to US mobile operators. The error indicates the program ID in the message request is not provisioned with the mobile operator.

Contact your account manager if you receive this error and believe that your program is provisioned or active with the mobile operator.

Retryable: Retry only once the campaign has been corrected with the mobile operator.

572

Campaign information is not provisioned for this carrier or is not active.

This error applies to messages sent to US mobile operators. OpenMarket has determined (before forwarding the message) that the program ID in the message request is not provisioned or is not currently active with the mobile operator.

Contact your account manager if you receive this error and believe that your program is provisioned or active with the mobile operator.

Retryable: Retry only if and when the campaign or program ID has been corrected.

573

Short code blocked by subscriber

The end user has asked their mobile operator to block any messages sent from your short code. Additional messages from the same short code must not be sent to the phone number unless the end user opts in again.

Retryable: no

574

Subscribers are not allowed to receive or send messages on this short code.

Indicates that for a given short code, new subscribers are not allowed to receive or send messages. However, existing subscribers are still allowed to receive and send messages.

This error is returned by Sprint US and Virgin Mobile USA.

Contact your OpenMarket account manager if you are unaware of why you have received this error.

Retryable: no

575

Account not permitted to submit preview requests

Retryable: no
603 Content blocked by user opt-out (MO: STOP)

This code can be returned in a delivery receipt for an MT originating from a North American, SMS-enabled toll-free number or an SMS-enabled landline number. Messaging can resume to the end user if the end user opts back in to your program.

Retryable: no

810

Failed message delivery

The mobile operator failed to get the text message to the end user's handset. This code is used when the mobile operator does not want retry attempts for the message.

Retryable: no

815

Message Delivery Error - Message submitted to but not acknowledged by carrier

You can retry this message; however, it is possible that the end user will receive the message multiple times.

Retryable: yes

1000

System error: General error occurred while processing request

Retryable: no

1010

Temporary internal system error

Retryable: yes

1020

Temporary external system error

If retries fail beyond the recommended retry period please contact OpenMarket Support for assistance troubleshooting.

All Carriers: Retry every 24 hours for a period of seven days.

T-Mobile USA: A 1020 response for for this carrier may either indicate a system error within T-Mobile USA or the following for the phone number:

Content Blocking/Blacklisting/Family Allowance is enabled. It is important to note the only way family allowance; content blocking or blacklisting occurs is if the mobile subscriber called into T-Mobile customer care and specifically requested blocking of short code services.

T-Mobile USA does not provide sufficient detail for OpenMarket to distinguish between the two potential causes for the 1020 response code.

Retryable: yes

1030

The mobile operator is experiencing an outage or system error during which they do not want messages retried.

Check the system status as reported by OpenMarket via email and on Customer Center, and use a slow retry strategy to test for connectivity; e.g. one request attempt every 20 minutes.

Retryable: no

3041

US standard rate message blocked by the OpenMarket deactivated numbers firewall

Occurs when a US standard rate SMS message is sent to a deactivated number.

Retryable: no