Optional SMPP parameters

On this page, you can read about what optional parameters are where they can be given and how they can be customized within the SMPP connection. This guide also gives a definition to what TLV field means and helps to carry out the customization of optional parameters.

In certain cases, it is advisable to add extra parameters to SMPP connection. These parameters are inserted into TLV fields. The fill-out of these fields is only optional and depends on the service provider's requirements. Ozeki NG SMS Gateway supports the functionality of this solution. The following sections are going to demonstrate the use and features of TLV field and explain how to fill them out with optional SMPP parameters.

What does TLV stand for?

TLV is a data type, a structure which enables the addition of new parameters to SMPP PDU. TLV is the acronym of Tag Length Value. TLVs are often called 'optional fields'. The TLV extra parameters were added to the SMPP protocol in version 3.4. TLV's can be added as byte stream at the end of the standard SMPP PDU's. The first two bytes give the length of the parameter, the third and fourth byte indicate the value of the actual data which go directly after the set bytes.

General

You need to install Ozeki NG SMS Gateway as well as SMPP service provider to send SMS. After configuration the system may require more parameters to gain total functionality. The extra parameters are called TLVs and they are used to maintain the optimal performance of the system.

Note: This solution is only available in Ozeki NG SMS Gateway v3.15.33 or above!

Customization

1. Send SMS with general customization of TLV parameters

If you customize your parameters according to the followings, all the messages sent through this SMPP connection will be sent out containing this optional field. After the configuration of SMPP connection further parameters can be set. Click on the Configure menu and select the Message submission tab. Fill in the Optional parameter box with the data as in the example in Figure 1.

optional parameter box
Figure 1 - Optional parameter box

I send a test message afterwards (Figure 2).

test message
Figure 2 - Test message

The success of configuration can be checked at the Events of SMPP service provider. At the end of the PDU you can view the customized parameters the same way as in Figure 3.

tlv parameters in log
Figure 3 - TLV parameters in log

2. Customizing the optional parameters with each SMS

It is possible to set the optional parameter with each SMS. This way, it can be determined which TLV value is added to the PDU at the SMPP connection. There are two ways to pre-determine the optional field: Database user or HTTP API.

Database user

To determine the optional parameters install a Database user. After installation, log in Ozeki NG SMS Gateway and enter the Configure menu in Database user. The name of the field is already containing data. The data is placed after the "tlv_" part. This is the Tag of the TLV field. The data returned in this field will be the Value of the TLV. The Length of the customized TLV field will be calculated from the returned data. To customize the Database user, click on the SQL for sending tab and type the "tlv_" keyword and the TLV tag's value into the Polling box as the example shows in Figure 4.

the tlv tag
Figure 4 - TLV tag

In this example the SQL field name is "tlv_5721". The TLV Tag is 5721. The data returned in this SQL field is '38353334322213'. This will be the TLV Value. The TLV Length will be calculated from the TLV Value.

Enter SQL prompt and give an SQL query. An example is shown in Figure 5.

sql query
Figure 5 - SQL query

In the example the number in tlv_5721 is the TLV Tag, which has a Value,'38353334322213'. The Length is determined by the Value which is '0007'.

The success of configuration can be checked at the Events of SMPP service provider. At the end of the PDU you can view the customized parameters the same way as in Figure 6.

log message
Figure 6 - Log message

HTTP API

Optional parameters can be requested in HTTP API as well. The customization of TLV parameters occurs the same way as in case of Database user. The "tlv_" is the TLV field containing the TLV Tag. The data returned is again the Value of the TLV and the Length is calculated from it. To do the customization insert an HTTP request into your browser. Below is an example.

HTTP request 

http://127.0.0.1:9501/api?action=sendmessage&username=admin&password=abc123&recipient
=06301234567&tlv_5721=38353334322213&messagetype=SMS:TEXT&messagedata=Hello+world

You can see in the response (Figure 7) that the Ozeki NG SMS Gateway has accepted the message for sending.

http response in xml
Figure 7 - HTTP response in xml

The success of configuration can be checked at the Events of SMPP provider. At the end of the PDU you can view the customized parameters the same way as in Figure 8.

tlv parameters in http log message
Figure 8 - TLV parameters in HTTP log message

In the example the number in tlv_5721 is the TLV Tag, which has a Value,'38353334322213'. The Length is determined by the Value '0007'.

More information