proto_smpp module


Table of Contents

1. Admin Guide
1.1. Overview
1.2. SIP to SMPP bridging
1.3. SMPP to SIP bridging
1.4. SMSC binding
1.5. Dependencies
1.5.1. OpenSIPS Modules
1.5.2. Dependencies of external libraries
1.6. OpenSIPS Exported parameters
1.6.1. db_url (string)
1.6.2. smpp_port (integer)
1.6.3. smpp_max_msg_chunks (integer)
1.6.4. smpp_send_timeout (integer)
1.6.5. outbound_uri (string)
1.6.6. smpp_table (string)
1.6.7. name_col (string)
1.6.8. ip_col (string)
1.6.9. port_col (string)
1.6.10. system_id_col (string)
1.6.11. password_col (string)
1.6.12. system_type_col (string)
1.6.13. src_ton_col (string)
1.6.14. src_npi_col (string)
1.6.15. dst_ton_col (string)
1.6.16. dst_npi_col (string)
1.6.17. session_type_col (string)
1.7. Exported Functions
1.7.1. send_smpp_message(smsc_name, [from],[to],[body],[utf-16],[delivery_receipt])
2. Contributors
2.1. By Commit Statistics
2.2. By Commit Activity
3. Documentation
3.1. Contributors

List of Tables

2.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)
2.2. Most recently active contributors(1) to this module

List of Examples

1.1. Set db_url parameter
1.2. Set smpp_port variable
1.3. Set smpp_max_msg_chunks parameter
1.4. Set smpp_send_timeout parameter
1.5. Set outbound_uri parameter
1.6. Set smpp_table parameter
1.7. Set name_col parameter
1.8. Set ip_col parameter
1.9. Set port_col parameter
1.10. Set system_id_col parameter
1.11. Set password_col parameter
1.12. Set system_type_col parameter
1.13. Set src_ton_col parameter
1.14. Set src_npi_col parameter
1.15. Set dst_ton_col parameter
1.16. Set dst_npi_col parameter
1.17. Set session_type_col parameter
1.18. send_smpp_message() usage

Chapter 1. Admin Guide

1.1. Overview

This module offers interoperability between SIP and SMPP (Short Message Peer-to-Peer) protocols. It provides the means to build a messaging gateway/bridge between the two protocols, being able to convert messages from both directions.

  • SIP to SMPP - messages coming from SIP can be converted to a SMPP PDU (Protocol Data Unit) message and sent further to a SMSC (Short Message Service Center).

  • SMPP to SIP - the module can act as an ESME (External Short Messaging Entity), receiving messages from a SMSC and converting them to a SIP Message that is sent further to a SIP proxy.

The module is compatible with the SMPP v3.4 specifications.

1.2. SIP to SMPP bridging

In order to convert a SIP message to a SMPP all you need to do is to call the send_smpp_message() function, indicating the SMSc you want to send the message to. The module will build the PDU according to the parameters provisioned in the database.

1.3. SMPP to SIP bridging

When bridging a message received over the SMPP interface, OpenSIPS builds a SIP Message and sends it to the outbound proxy identified by the outbound_uri module's parameter.

1.4. SMSC binding

In order to be able to deliver messages to SMSc, an ESME needs to first bind to the SMSc. This is done at OpenSIPS startup by sending a SMPP bind_transciever command to connect to the SMSc, or an outbind command to inform an SMSc it can now bind to our gateway.

The description of all SMSc servers is provisioned in the database. For each server, one can cofigure the following information:

  • Name - an unique name given to the SMSc that is used to reference this SMSc in the OpenSIPS script.

  • IP - The IP the SMSc is listening on for new bindings/connections.

  • Port - The TCP port that the SMSc is listening on for new bindings/connections.

  • System ID - Also known as the User name that is used to authenticate to the SMSc.

  • Password - A password used to authenticate to the SMSc.

  • System Type - Usually SMPP, this field is required by some SMPP providers.

  • Source Type of Number (TON) - Specifies the format of the number used to send messages from. Some comon values are:

    • 0 - Unknown

    • 1 - International

    • 2 - National

    • 3 - Network Specific

    • 4 - Subscriber Number

    • 5 - Alphanumeric

    • 6 - Abbreviated

    Default value is 0 - Unknown.

  • Source Number Plan Indicator (NPI) - Specifies the numbering scheme of the number used to send messages from. Some comon values are:

    • 0 - Unknown

    • 1 - ISDN/telephone numbering plan (E163/E164)

    • 3 - Data numbering plan (X.121)

    • 4 - Telex numbering plan (F.69)

    • 6 - Land Mobile (E.212)

    • 8 - National numbering plan

    • 9 - Private numbering plan

    • 10 - ERMES numbering plan (ETSI DE/PS 3 01-3)

    • 13 - Internet (IP)

    • 18 - WAP Client Id (to be defined by WAP Forum)

    Default value is 0 - Unknown.

  • Destination Type of Number (TON) - Specifies the format of the number used to send messages to. Can have the same values as Source Type of Number (TON) and default value is 0 - Unknown.

  • Destination Number Plan Indicator (NPI) - Specifies the numbering scheme of the number used to send messages to. Can have the same values as Source Number Plan Indicator (NPI) and default value is 0 - Unknown.

  • Session Type - Specifies what type of session should be used to connecto th the SMSc. Possible values are:

    • 1 - Transciever

    • 2 - Transmitter

    • 3 - Receiver

    • 4 - Outbind

    Default value is 1 - Transciever.

When OpenSIPS starts up, it reads all SMSc specifications from the database and triggers a binding with them. Note: reloading the SMSc database is not yet supported, but it is a work in progress.

Each SMPP connection is periodically pinged (currently every 5 seconds) using enquire_link SMPP commands to keep the connection active.

1.5. Dependencies

1.5.1. OpenSIPS Modules

The following modules must be loaded before this module:

  • database -- Any database module

1.5.2. Dependencies of external libraries

  • None.

1.6. OpenSIPS Exported parameters

All these parameters can be used from the opensips.cfg file, to configure the behavior of OpenSIPS-SMPP gateway.

1.6.1. db_url (string)

The database handler where the SMPP connection will be stored. This parameter is mandatory.

Default value is unset.

Example 1.1. Set db_url parameter

...
modparam("proto_smpp", "db_url", "dbdriver://username:password@dbhost/dbname")
...

1.6.2. smpp_port (integer)

Used to change the default value of the SMPP port used to listen for new connections.

Default value is 2775.

Example 1.2. Set smpp_port variable

...
modparam("proto_smpp", "smpp_port", 27775)
...
		

1.6.3. smpp_max_msg_chunks (integer)

The maximum number of chunks in which a SMPP message is expected to arrive via TCP. If a received packet is more fragmented than this, the connection is dropped (either the connection is very overloaded and this leads to high fragmentation - or we are the victim of an ongoing attack where the attacker is sending very fragmented traffic in order to decrease server performance).

Default value is 8.

Example 1.3. Set smpp_max_msg_chunks parameter

...
modparam("proto_smpp", "smpp_max_msg_chunks", 32)
...

1.6.4. smpp_send_timeout (integer)

Time in milliseconds after a TCP connection will be closed if it is not available for blocking writing in this interval (and OpenSIPS wants to send something on it).

Default value is 100 ms.

Example 1.4. Set smpp_send_timeout parameter

...
modparam("proto_smpp", "smpp_send_timeout", 200)
...

1.6.5. outbound_uri (string)

This parameter represents the URI of the outbound proxy used to send a message converted from SMPP to SIP.

Default value is None.

Example 1.5. Set outbound_uri parameter

...
modparam("proto_smpp", "outbound_uri", "sip:127.0.0.1:5060")
...

1.6.6. smpp_table (string)

The name of the database table containing definitions of the SMSc servers used to connect to.

Default value is smpp.

Example 1.6. Set smpp_table parameter

...
modparam("proto_smpp", "smpp_table", "smsc")
...


1.6.7. name_col (string)

The name of the column that holds the SMSc identifier used by the send_smpp_message() function.

Default value is name.

Example 1.7. Set name_col parameter

...
modparam("proto_smpp", "name_col", "smsc_name")
...


1.6.8. ip_col (string)

The name of the column that holds the IP of the SMSc.

Default value is ip.

Example 1.8. Set ip_col parameter

...
modparam("proto_smpp", "ip_col", "smsc_ip")
...


1.6.9. port_col (string)

The name of the column that holds the SMSc port.

Default value is port.

Example 1.9. Set port_col parameter

...
modparam("proto_smpp", "port_col", "smsc_port")
...


1.6.10. system_id_col (string)

The name of the column that holds the SMSc System ID.

Default value is system_id.

Example 1.10. Set system_id_col parameter

...
modparam("proto_smpp", "system_id_col", "smsc_system_id")
...


1.6.11. password_col (string)

The name of the password column used to authenticate the SMSc.

Default value is password.

Example 1.11. Set password_col parameter

...
modparam("proto_smpp", "password_col", "smsc_password")
...


1.6.12. system_type_col (string)

The name of the System Type column used to bind the SMSc.

Default value is system_type.

Example 1.12. Set system_type_col parameter

...
modparam("proto_smpp", "system_type_col", "smsc_system_type")
...


1.6.13. src_ton_col (string)

The name of the column that holds the Source TON values.

Default value is src_ton.

Example 1.13. Set src_ton_col parameter

...
modparam("proto_smpp", "src_ton_col", "smsc_src_ton")
...


1.6.14. src_npi_col (string)

The name of the column that holds the Source NPI values.

Default value is src_npi.

Example 1.14. Set src_npi_col parameter

...
modparam("proto_smpp", "src_npi_col", "smsc_src_npi")
...


1.6.15. dst_ton_col (string)

The name of the column that holds the Destination TON values.

Default value is dst_ton.

Example 1.15. Set dst_ton_col parameter

...
modparam("proto_smpp", "dst_ton_col", "smsc_dst_ton")
...


1.6.16. dst_npi_col (string)

The name of the column that holds the Destination NPI values.

Default value is dst_npi.

Example 1.16. Set dst_npi_col parameter

...
modparam("proto_smpp", "dst_npi_col", "smsc_dst_npi")
...


1.6.17. session_type_col (string)

The name of the column that holds the Session Type of the SMSc.

Default value is session_type.

Example 1.17. Set session_type_col parameter

...
modparam("proto_smpp", "session_type_col", "smsc_session_type")
...


1.7. Exported Functions

1.7.1.  send_smpp_message(smsc_name, [from],[to],[body],[utf-16],[delivery_receipt])

This function is used to convert a SIP message received in the OpenSIPS script to a SMPP PDU and send it to the smsc_name (string) received as parameter. The SMPP parameters used to construct the PDU are provisione in the database, and the command sent is either submit_sm or deliver_sm, depending on the type of the SMSc.

The function returns -2 if the SMSc the message should be sent does not exist in the database, -1 if there was an internal error, or positive value in case of success.

Meaning of the parameters is as follows:

  • sms_name (string) - name of the SMS to be used for sending the SMPP traffic.

  • from (string, optional) - the source number. If missing, the SIP message from username is used.

  • to (string, optional) - the destination number. If missing, the SIP request URI username is used.

  • body (string, optional) - the body of the SMS. If missing, the SIP message body is used.

  • UTF-16 (int, optional) - set to 1 if the body of the message is in UTF-16. format. If missing or 0, UTF-8 is used.

  • delivery_receipt (int, optional) - Whether the SMSC should confirm delivery for this SMS or not

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE or BRANCH_ROUTE.

Example 1.18. send_smpp_message() usage

...
    if (is_method("MESSAGE"))
			send_smpp_message("MY_SMSC");
...

Chapter 2. Contributors

2.1. By Commit Statistics

Table 2.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)

 NameDevScoreCommitsLines ++Lines --
1. Victor Ciurel (@victor-ciurel)802137601658
2. Razvan Crainea (@razvancrainea)70392044798
3. Vlad Paiu (@vladpaiu)8523437
4. Liviu Chircu (@liviuchircu)643832
5. Bogdan-Andrei Iancu (@bogdan-iancu)5373
6. Vlad Patrascu (@rvlad-patrascu)421013
7. Zero King (@l2dy)3142
8. Maksym Sobolyev (@sobomax)3111
9. Nick Altmann (@nikbyte)3111

(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)

(2) including any documentation-related commits, excluding merge commits. Regarding imported patches/code, we do our best to count the work on behalf of the proper owner, as per the "fix_authors" and "mod_renames" arrays in opensips/doc/build-contrib.sh. If you identify any patches/commits which do not get properly attributed to you, please submit a pull request which extends "fix_authors" and/or "mod_renames".

(3) ignoring whitespace edits, renamed files and auto-generated files

2.2. By Commit Activity

Table 2.2. Most recently active contributors(1) to this module

 NameCommit Activity
1. Maksym Sobolyev (@sobomax)Feb 2023 - Feb 2023
2. Nick Altmann (@nikbyte)May 2021 - May 2021
3. Bogdan-Andrei Iancu (@bogdan-iancu)Apr 2019 - Apr 2021
4. Liviu Chircu (@liviuchircu)May 2020 - Jan 2021
5. Zero King (@l2dy)Mar 2020 - Mar 2020
6. Razvan Crainea (@razvancrainea)Jan 2019 - Jan 2020
7. Vlad Paiu (@vladpaiu)May 2019 - Sep 2019
8. Vlad Patrascu (@rvlad-patrascu)Apr 2019 - Apr 2019
9. Victor Ciurel (@victor-ciurel)Sep 2017 - Jan 2019

(1) including any documentation-related commits, excluding merge commits

Chapter 3. Documentation

3.1. Contributors

Last edited by: Razvan Crainea (@razvancrainea), Vlad Paiu (@vladpaiu), Vlad Patrascu (@rvlad-patrascu).

Documentation Copyrights: