Sending and Receiving SMS
Overview
The SMPP service may receive messages to send to the network via multiple methods:
- 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.
- 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:
- JSON output when the processing type is
unpack
. - 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:
|
message_class |
String | (various) | No | normal |
The message class. Must be one of:
|
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:
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:
|
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 value must 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:
- If
name
is defined in the SMS input, the TLV configuration from SMPP TLV set will be used as a base. Any information provided in the input will override base configuration. - If
name
is not provided, only the input information will be used to configure and fill the 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.