Sending and Receiving SMS

Overview

The SMPP service may receive messages to send to the network via multiple methods:

  1. As JSON input, usually from another SMPP service operating with the unpack processing type for segmentation or relay or from the Redis or SMS Gateway services for message building and sending.
  2. As a pre-encoded SMPP message, usually from another SMPP service operating with the relay processing type.

Similarly, messages received from the network are sent by the SMPP service EventBus message handler as:

  1. JSON output when the processing type is unpack.
  2. Encoded SMPP messages when the processing type is relay.

SMPP Message JSON

The SMPP service supports input and output of JSON documents with the following syntax:

{
  "source_address": "<message source address>",
  "destination_address": "<message destination address>",
  "message_text": "<message text>",
  "message_class": "<message class>",
  "schedule_delivery_time":"<date for delivery",
  "validity_period": "<validity period of message>",
  "udh_port_addressing_size", <number of bits for UDH ports>
  "udh_source_port": "<userdata source port>",
  "udh_destination_port": "<userdata destination port>",
  "encoding_scheme": "<message encoding scheme>",
  "tlvs": [ 
    // TLV definitions
  ]
}

The content of these fields is as below.

Field Type SMPP Field(s) Required
(Input)?
Default
(Input)
Description
source_address String source_addr
source_addr_npi
source_addr_ton
Yes - The source party identifier, possibly modified by normalisation, if enabled.
destination_address String destination_address
dest_addr_npi
dest_addr_ton
Yes - The destination party identifier, possibly modified by normalisation, if enabled.
message_text String short_message
message_payload
Yes - The (plaintext) message text to send. Will be encoded in the outgoing message as per the SMPP service’s data coding configuration. When sending SMS, the SMPP message_payload TLV is used if the encoded text exceeds the length of the short_message field.
message_type String command_id No submit The SMPP message type. Must be one of:
  • submit for SMPP submit_sm messages (to mobiles)
  • deliver for SMPP deliver_sm messages (from mobiles)
message_class String (various) No normal The message class. Must be one of:
  • normal
  • flash
When sending SMS, this is applied to the outgoing message in line with the the configured flash encode mode for the SMPP service.
schedule_delivery_time String schedule_delivery_time No - The date for message delivery, specified in SMPP format, e.g. 191220230000012+.
validity_period String validity_period No - Validity period of message, specified in SMPP format, e.g. 191220230000012+.
registered_delivery Integer registered_delivery No 0 Whether a delivery receipt is requested for the message. Only applicable when the message_type is submit.
udh_port_address_size Integer (userdata header) No 16 The number of bits used for userdata port addressing addresses, either 8 or 16.
udh_source_port Integer (userdata header) No - The source port in the userdata header for application port messaging. If specified as input, udh_destination_port must also be specified.
udh_destination_port Integer (userdata header) No - The destination port in the userdata header for application port messaging. If specified as input, udh_source_port must also be specified.
encoding_schemes Array of String (userdata encoding) No (from configuration) When sending SMS, the allowable encoding scheme(s) to use for encoding the text of the outbound message. If not speciifed for input, all possible encodings from the outgoing SMPP service endpoint’s data coding configuration may be used. Included for received messages only if the configuration option preserve_encodings is enabled.
message_number Integer (various) No - The message number of this message, if it is already segmented. When sending SMS, this should only be set for messages received as SMPP messages from the network.
total_messages Integer (various) No - The total number of message segments for this message, if it is already segmented. When sending SMS, this should only be set for messages received as SMPP messages from the network.
tlvs Array (various) No (empty) The TLVs for this message. Each array entry must be an SMPP TLV configuration object. When sending SMS, TLVs that will automatically be included for message segmentation, text encoding, or flash encode mode should not be included, as they are generated automatically as required. Similarly, when messages are received from the network, TLVs that are used in determining the message_text, message_class, message_number, or total_messages are not included.
tlvs Array (various) No (empty) The TLVs for this message. For messages received from the network, the TLV tag, type, and value will be included. Integer TLVs will also have their length recorded. When sending SMS, each array entry may be:
  • A String, in which case all TLV details will be retrieved from the SMPP service TLV configuration, matching on name, or
  • An Object, in which case the fields may be specified as per the SMPP JSON input. If a TLV with a matching name is found, its details will be used as a base, with any input fields overriding any configured values.
When sending SMS, TLVs that will automatically be included for message segmentation, text encoding, or flash encode mode should not be specified, as they are generated automatically as required. Similarly, when messages are received from the network, TLVs that are used in determining the message_text, message_class, message_number, or total_messages are not included.

Note that if message_number and total_messages are set in JSON input and the outgoing message requires further segmentation due to the outgoing SMPP service endpoint’s data coding configuration, the outgoing message number and total will be scaled to match the new segmentation. This may lead to cases where an incorrect total number of messages is specified (e.g. if the pre-segmentated message had little userdata in the final segment).

SMPP JSON TLV Configuration

Each TLV specified in SMPP JSON takes the form:

{
  "tag": <TLV decimal tag>,
  "type": "<TLV type>",
  "value": "<TLV value>",
  "length": <TLV length>
}

Each TLV definition in a TLV set may have the following parameters:

Field Type Required? Default Description
name String Conditional - The name of the TLV, as defined in the SMPP configuration.
tag Integer Conditional - The decimal tag value to set for the TLV, in the range 0..65535.
type String Conditional - The type of TLV. Possible values:
  • integer - an SMPP integer
  • cstring - an SMPP C-Octet string
  • octets - an SMPP Octet string
value String or Integer Conditional - The value of the TLV. For integer TLVs, must be an Integer, otherwise must be a String.
length Integer Conditional - The fixed length of the TLV value. Required for integer TLVs, where it sets the number of bytes to use for the of the value; must be either 1, 2, or 4. If specified for octets TLV types, the given value must be exactly this long. If specified for cstring TLVs, the given valuemust be one character less than this to account for the required null suffix.
min_length Integer Conditional 0 The minimum length of the TLV value, following the rules given for length.
max_length Integer Conditional The maximum length of the TLV value, following the rules given for length.

When constructing TLVs for sent SMS, either of the following modes may apply for each TLV:

Regardless of the mode used to populate the TLV, the end result must have at least a tag, a type, and a value (regardless of the source of the information). TLVs of type integer must have a length defined in some manner, but for other TLV types length constraints are optional. When TLV length is specified, either length or one or both of min-length or max-length may be used.

TLVs received from the network will only have a length specified for integer TLVs.

Some TLVs may automatically be inserted into outgoing messages as per the SMPP service’s message segmentation, text encoding, or flash encode mode configuration. Other TLVs will only be included in sent SMS if the input specified them to be sent.

Encoded SMPP Messages

The SMPP service also accepts pre-encoded SMS SMPP messages for delivery to the network. In these cases, the message is sent as-received, and no segmentation nor transcoding occurs. Any responses received from the network for pre-encoded messages are returned as-is without decoding or analysis. For example, if a submit_sm message was originally sent out, the returned submit_sm_resp (if any) is returned as-is in the response event.

If the SMPP service endpoint is operating in relay mode, it will forward all SMPP messages from the network as-received with no decoding or analysis.