Send a Mobile Terminated (MT) message

The MT operation allows you to submit a short message to OpenMarket for transmission to a user's handset. OpenMarket supports the submit_sm PDU request and submit_sm_resp PDUs. The PDU request is composed of mandatory and optional parameters, as well as optional OpenMarket custom TLVs. The submit_sm_resp PDU echoes back the header information and an MT command status code indicating the outcome of the request. If custom OpenMarket TLVs are implemented on your account, a TLV-specific command status code is returned.

In all cases where the length of a submitted parameter is greater than the maximum allowed length, an unbind command will be returned by OpenMarket.

In this topic:

submit_sm PDU

The submit_sm PDU is composed of a header and a body that contains mandatory and optional PDU and OpenMarket TLV parameters, described in the following sections. If a bind is registered, but the length of a submitted parameter is greater than the maximum specified length, the bind will drop. A connection must then be re-established.

submit_sm PDU header parameters

Parameter

Description

Command Length

Length of the PDU in octets.


Size (octets): 4

Type: Integer

Value: Customer-supplied

Command ID

Identifies the type of message the SMPP PDU represents.


Size (octets): 4

Type: Integer

Value: 0x04

Command Status

This field is not used. Set to 0x00 (NULL).


Size (octets): 4

Type: Integer

Value: 0x00

Sequence Number

A unique customer-set sequence number. The associated submit_sm_resp PDU echoes this sequence number back in the response.


Size (octets): 4

Type: Integer

Value: Customer-supplied

submit_sm mandatory PDU parameters

Parameter

Description

Service Type

Use a value of OMV4 in the submit_sm service type parameter to identify your MT as a V4 MT. You may have your account default set to expect all V4 MTs without submitting a value for service type. Contact your account manager or customer support if you wish to do so. If the service type does not match the defined v4 string, the operation then assumes that the request uses the v3 API and then passes the request using that API. The request will fail, however, if it encounters any unexpected v4 parameters in the request.


Size (octets): Maximum is 6

Type: C-Octet String

Value:

  • OMV4 - If OMV4 is not the default for your account.
  • 0x00 - If OMV4 is the default for your account.

Source Address TON

The MT source address TON. If the value is not 0x01, 0x03, or 0x05, the MT is rejected with status code 0x48.


Size (octets): 1

Type: Integer

Value: The value of the MT Source Address TON. Only the following are supported:

  • 0x01 - phone number, starting with country code

  • 0x03 - national short code

  • 0x05 - alphanumeric

If the source address is omitted, and the Automatic Originator Selection (AOS) used instead, the field should be NULL(0x00), indicating unknown. In addition,

  • TON 0x01 and TON 0x03 source addresses may only contain digits.
  • TON 0x05 source addresses may only contain ASCII characters.

Source Address NPI

The source address numbering plan indicator. If the Source Address NPI is unknown, then set this field to NULL.


Size (octets):1

Type: Integer

Value: 0x00 or 0x01

Source Address

Address of the originating short messaging entity (SME). When submitting the source address, you must not use the leading plus (+) sign.

  • If the source_address is greater than the maximum allowed length, the bind is dropped after SMPPGW sends an Unbind PDU request to the customer.

  • If the source_address is supplied in the MT and the source address TON is 0x01 or 0x03, and the source address is not provisioned for the customer account, then the MT is rejected with command status 0xA.


Size (octets): Minimum - 1, maximum - 21

Type: C-Octet String

Value: The MT source address. If the source address is omitted, and the Automatic Originator Selection (AOS) used instead, the field should be NULL (0x00), indicating unknown.

Destination Address TON

Type of number (TON) for the destination. For example, this might be an international or domestic number. If unknown, this value will be NULL. If the value is not equal to 0x01, then the MT is rejected with status code 0x50.


Size (octets): 1

Type: Integer

Value: 0x01

Destination Address NPI

The destination address numbering plan indicator. This parameter is always set to 0x01.


Size (octets): 1

Type: Integer

Value: 0x01

Destination Address

Address of the terminating destination. If the value is NULL or not within the defined length limits, the MT is rejected with status code 0xB.



Size (octets): Variable, but a maximum of 21

Type: C-Octet String

Value: The MT destination address. This must be a phone number that includes the country code. Do not include the leading plus (+) character. For example:

  • 12125550123 (US number)
  • 447700900750 (UK number)
  • 61491570156 (Australian number)

ESM Class

The message mode and type, indicating any special message attributes associated with the SMS.

  • If the value of the ESM Class is not equal to 0x00, 0x03, 0x40, or 0x43, the MT is rejected with status code 0x43.

  • If the value of the ESM Class equals 0x40 or 0x43, and there is no valid UDH at the start of the short message, the MT is rejected with status code 0x409.


Size (octets): 1

Type: Integer

Value:

  • 0x00 or 0x03 to store and forward

  • 0x40 or 0x43 if the message contains a UDH

Protocol ID

The network protocol identifier.


Size (octets): 1

Type: Integer

Value: Network-specific value. If non-NULL, the value is passed through to the mobile operator.

Priority Flag

Not used. Set to 0x00 (NULL). If a non-null value is supplied, it will be ignored.


Size (octets): 1

Type: Integer

Value: 0x00

Schedule delivery time

Not used. Set to 0x00 (NULL). If the value of this parameter is anything other than NULL, the MT is rejected with status code 0x61.


Size (octets): 1

Type: C-Octet String

Value: 0x00

Validity Period

If the default mobile operator validity period is requested, set to 0x0 (NULL). Otherwise, see section 7.1, "Time Definitions", in the SMPP v3.4 specification for instructions on setting a non-zero validity period in either absolute or relative time format.


Size (octets): 1 or 17

Type: C-Octet String

Value: No default value is selected. If no value is supplied, the mobile operator's default value is used.

Registered Delivery

Used to request an SMSC delivery receipt and/or SME-originated acknowledgment. If the value is not one of the supported values, the MT is rejected with status code 0x7.


Size (octets): 1

Type: Integer

Value: Use one of the following:

  • 0x00 - No receipt
  • 0x01 - Final delivery receipt. Delivery receipt details are returned to the source address.

Replace if Present Flag

Not used. Set to 0x00 (NULL). If the value of this parameter is anything other than NULL, the MT is rejected with status code 0x54.


Size (octets): 1

Type: Integer

Value: 0x00

Data Coding

Defines the encoding scheme of the short message user data. If the value is not one of the supported values, the MT is rejected with status 0x406.

Size (octets): 1

Type: Integer

Value: Use one of the following:

  • 0x00 - the default character set on the account.
  • 0x01 - IA5
  • 0x02,0x04 - binary
  • 0x03 - Latin1
  • 0x08 - UCS-2
  • Flash variants - 0xF0 (240), 0xF6 (246), 0x10 (16), 0x18 (24)

See Data Coding Scheme for more information.

Short Message Default Message ID

Not used. Set to 0x00 (NULL). If the value of this field is anything other than NULL, the MT is rejected with status 0x63.


Size (octets): 1

Type: Integer

Value: 0x00

Short Message Length

The length of the short message in the delivery receipt. If the Short Message content is greater than that of the specified Short Message Length, the message is truncated to the length specified by this parameter.


Size (octets): 1

Type: Integer

Value: 0 to 160

Short Message

Populated with information about the submitted date, delivery date, message state, the OpenMarket MT status code, and the OpenMarket MT ticket ID.


Size (octets): Variable, 0 - 160

Type: Octet String

Value: The message content. If the Short Message is greater than the Short Message Length, it is truncated to the value set by the Short Message Length.

Note: Although OpenMarket might not use or support a particular parameter in an operation, that parameter must still be passed using a 0x00 (NULL) value.

submit_sm OpenMarket custom TLVs

These are the optional custom OpenMarket deliver TLV parameters. They are only returned if your account has been configured to receive them. To enable custom TLVs returned in the MT API, contact OpenMarket Support.

Operator ID

Tag

Description

0x2150

The OpenMarket mobile operator identifier. See Mobile Operator IDs for more information.


Type: Short

Size (octets): 2

Value: Mobile operator-dependent

Note 1

Tag

Description

0x2168

Use this to add data to the request that you may want available in reports, such as individual identifiers—for example, your own transaction, ticket, or system ID. It has no effect on the message or its delivery. This is a free-form text field that can be from one to 200 characters in length.


Type: Octet String

Size (octets): Variable, from 1-200

Value: Customer-defined

Note 2

Tag

Description

0x3031

Use this to add data to the request that you may want available in reports, such as individual identifier—for example, your own transaction, ticket, or system IDs. It has no effect on the message or its delivery. The value is free-form text that is 1 to 200 characters in length.


Type: Octet String

Size (octets): Variable, from 1-200

Value: Customer-defined

Program ID

Tag

Description

0x2157

This identifies a pre-provisioned program linked to the short code messaging service you are providing. OpenMarket will provide you with the value, which will be 1 - 50 characters, and is not case-sensitive. Customers sending MTs to US operators who do not support TLVs defined by OpenMarket can work with account managers to provision a NULL program ID for a given short code/US operator pair.


Type: Octet String

Size (octets): Variable, 1 - 50

Value: Mobile operator-dependent

Interaction

Tag

Description

0x219B

Indicates whether or not you want to use a number to which users can respond. If not supplied, the SMS Service determines the value to use based on the Source Address and Source Address TON.


Type: Octet String

Size (octets): 7

Value: One of the following:

    • one-way - when you do not need end users to respond to the message; suitable message originators are alphanumeric strings and virtual mobile numbers (VMNs).

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

Promotional

Tag

Description

0x219C

Indicates whether or not the message is promotional. This TLV is used for IN MTs. Values are: If not supplied, and IN (India) is the destination address country, 1 is used as the default.


Type: Byte

Size (octets): 1

Value: One of the following:

    • 0x00 - promotional
    • 0x01 - not promotional

submit_sm_resp

A submit_sm_resp is returned for a submit_sm request. The response will include a status code indicating the result of the operation. All custom OpenMarket command status values are returned in a 0x4xx command status. See OpenMarket submit_sm_resp command status codes for custom TLVs for more details about this series of codes.

submit_sm_resp PDU parameters

Parameter

Description

Command Length

Length of the PDU in octets.


Size (octets): 4

Type: Integer

Value: Customer-supplied

Command ID

Identifies the type of message the SMPP PDU represents.


Size (octets): 4

Type: Integer

Value: 0x04

Command Status

Identifies the outcome of the submit_sm request.


Size (octets): 4

Type: Integer

Value: The status of the response. A status can be returned for either of the following:

  • An OpenMarket-specific status code for custom TLVs, which use codes in a 0x400 range.

  • A general response status code.

See submit_sm_resp command status codes for more information.

Sequence Number

The sequence number passed in the submit_sm request.


Size (octets): 4

Type: Integer

Value: Customer-supplied

Message ID

The OpenMarket ticket ID, used with delivery receipts.


Size (octets): Variable, with a maximum of 65

Type: C-Octet String

Value: The MT ticket identifier if a ticket ID was generated