SMPP TLV Optional Parameters
The SMPP protocol defines support for optional parameters, known as TLV parameters. Some TLV parameters are defined in the core specification, and TURAIN SMS may use them depending on configuration settings. These TLV parameters include message_payload, source_port, dest_port, sar_msg_ref_num, sar_total_segments, sar_segment_seqnum, payload_type, message_state and receipted_message_id. (There are also advanced configuration settings to generate values for user_message_reference and callback_num, which were required by specific customer implementations.)
SMS service providers are free to define their own TLV parameters, which sometimes may be required when interfacing with a mobile operator. These TLV parameters might include operator information for inbound messages, pricing information for premium rate SMS, or other security and fraud prevention parameters required by that service provider.
TURAIN SMS provides flexibility to configure support for custom TLV parameters as needed. TLV parameters must be manually defined to TURAIN SMS before they can be used.
TLV stands for Tag, Length and Value, which is the basic format of these parameters.
Tag is a numeric value, usually expressed as a hexadecimal value, that the provider defines for the parameter. These values are usually 0x1400 or higher for service provider specific parameters. While the parameter is logically thought of as a Name=Value pair, this number is used in the SMPP request instead of a parameter name.
Length and Value are used to encode the parameter value in the SMPP request.
Interpreting a TLV parameter can be tricky because the format of the value depends on how the provider defines the parameter. Values might be encoded as a string value, a numeric value, or binary data. For string values, it can sometimes be more complicated because the SMPP protocol defines two types of strings, a C format string that is null terminated (as is common for strings when working with the C programming language) and another that does not include the null terminator. Some provider parameter implementations can become confused over this minor difference.
Generally, to define a TLV parameter to TURAIN SMS, you need to know its Tag number (hexadecimal) and format of the value data.
When this is known, manually edit SMSGW.INI and create or modify an [SMPPOptions] section to define the parameter details.
The basic format is:
[SMPPOptions]
parametername=####,Type,Len
parametername is a descriptive name to be associated with the parameter. TURAIN SMS will use this name when converting the parameter to and from HTTP formats.
#### is the parameter tag number as a hexadecimal number. Do not include any prefix to indicate hex format…for example, 0x1400 is just 1400 for this parameter setting.
Type specifies the parameter type: Integer, String, CString or HexString.
Len is optional, but is usually required for Integer values to specify a 1, 2 or 4 byte value, as defined by the provider. (4 byte integer parameters require TURAIN SMS 2013.08.30 or later. Earlier versions of TURAIN SMS can only support 4 byte integers using the HexString format.)
CString is a text string that is null terminated (e.g., final 00 byte at the end), String is a text string that is not null-terminated.
HexString treats the value as binary data and converts it to a string of hex characters for HTTP (and back to binary for SMPP).
Len can be used for String or HexString to force a length (truncate value at length or pad with nulls). In most cases, Len is omitted from the parameter definition for String, CString and HexString format parameters, unless the provider requires the parameter to have a specific length. (TURAIN SMS will generate the L for the TLV based on actual value string length.)
Example
This is all easier to explain with an example.
For the purpose of this example, we will assume that our provider has defined a TLV parameter called request_id. It is a text string and has a tag number of 0x1555.
We define the following in SMSGW.INI:
[SMPPOptions] request_id=1555,String
If TURAIN SMS receives an SMS from the provider via SMPP which includes this parameter, accounting callbacks and 2-way commands will automatically have this parameter added to the HTTP request as &SMPPOption_request_id=xxxxx (xxxxx is the value of the parameter that was parsed from the message).
When submitting a message to TURAIN SMS via HTTP, this same &SMPPOption_request_id=xxxxx can be used to specify that the TLV parameter should be included when submitting the message to the SMPP provider.
To Always Include Parameter With A Default Value
If you want to automatically include a TLV parameter in every message without requiring it to be explicitly set for each message submission, it is possible to configure TURAIN SMS to use a default value for this parameter when submitting messages to your SMPP connection.
To define a default value for this parameter, manually edit the SMSGW.INI, and in the section header for an SMPP connection (e.g., [SMPP – ip.address:port]), add a “DefaultSMPPOptions=” setting, where the value of this setting can contain any of the “SMPPOptions” settings. For example:
DefaultSMPPOptions=request_id=myrequest
(If you have multiple SMPPOptions parameters defined that need to be set as default, separate them with a “;”. For example: DefaultSMPPOptions=request_id=myrequest;otherparm=othervalue)
To Include TLV Parameter In 2-Way SMS Reply
Another common requirement for some TLV parameter is that when generating an automatic reply to a message, the value of the TLV parameter in the received message must be copied over to the new reply message. If you are using 2-way SMS to send replies to incoming messages (“Command returns response text” is checked for the 2-way command), add 2WayReplyCopySMPPOptions=requestid to the [SMSGW] section of SMSGW.INI. This setting tells TURAIN SMS that if it is processing a 2-way command reply, it should automatically copy the request_id TLV parameter from the source message to the reply.
