While the SIP protocol is one of the most popular protocols used for voice calls, the SMPP (Short Message Peer-to-Peer) is one of the most widely used protocols for sending text messages. Having both of them offered by your service enhances your platform with more compatibility and flexibility.

In order for your customers to have an unified experience, one has to ensure that messages coming from one side are visible and accessible by the other side. For example, someone might send an SMS that comes to your platform over SMPP and it needs to be delivered to a SIP endpoint. Since the two protocols are incompatible (see Compatibility below), there needs to be a tool that does bridging between the two protocols.

Luckily, OpenSIPS 3.0 now features a SIP to SMPP gateway using the new proto_smpp module! This module acts as an ESMEs (External Short Messaging Entity) that is able to connect to a SMSCs (Short Message Service Center) and exchange text messages with it.

Compatibility

Messages in SMPP are binary encoded PDUs (protocol data units) that are carried between the entities involved over TCP. Since it’s using a stream oriented transport protocol, the SMPP protocol has a plethora of commands that are used to keep a SMPP session active and exchange data between endpoints: when starting a SMPP session, an ESME needs to send one of four bind commands (bind_receiver, bind_transmitter, bind_transceiver, or outbind) to the SMSC, depending on its role (receiver, transmitter, or both). Each command has to be confirmed (for example using a bind_receiver_resp acknowledgement for a bind_receiver command). After that, pinging (enquire_link) has to be sent periodically to keep the connection open. Finally, when a text message is sent, a different command command is used, depending on the state of the component.

On the other hand, in SIP things are simpler – messages are constructed using plain text SIP MESSAGE packets (RFC 3428). These messages can be exchanged between SIP endpoints and proxies using any transport protocol supported by SIP (UDP, TCP, TLS, SCTP, WebSocket), the most common one being UDP. Each SIP message sent needs to be confirmed by the receiver using a 200 OK. And that’s it.

Therefore it is clear that the two protocols are not compatible from a behavioral point of view. However, at the end of the day, both protocols are used to transport (mainly) text messages. So as long as we have the actual message payload and meta-data, all we have to do is to building the message according to the transport protocol we need to use.

Configuration

In order to use SMPP connections in your OpenSIPS install, you have to load the proto_smpp module and define a listener that will be used for communication:

listen = smpp:127.0.0.1:2775
...
load_module "proto_smpp.so"

As noted in previous section, for an SMSC to be able to deliver messages to an ESME, all SMPP connections need to be created beforehand. This is done automatically by OpenSIPS at startup. All connections that have to be initiated are described in a database, along with all the parameters they need. So the next thing that has to be configured in the script is a connection to a database:

mysql://opensips:opensipsrw@localhost/opensips

Below you can find an example of a MySQL record that describes an SMPP connection used to connect to an SMSC as a transceiver (session_type=1):

        name: SMPP_test
          ip: 127.0.0.1
        port: 2777
   system_id: smpp
    password: test
 system_type: 
     src_ton: 2
     src_npi: 1
     dst_ton: 2
     dst_npi: 1
session_type: 1

• name: represents an arbitrary, unique name that will be used to reference this SMPP connection from the script
• ip and port: the TCP information needed to connect to the SMSC
• system_id (also known as the user name) and password are used for authentication
• system_type is a field required by some SMPP providers, and it is usually used to identify the types of services that connection is allowed to use
• TON (Type of Number) for source (src_ton) and destination (dst_ton) indicate the format of the numbers used for sender and receiver. Some common values are:
  • 0 – Unknown
  • 1 – International
  • 2 – National
  • 3 – Network Specific
  • 4 – Subscriber Number
  • 5 – Alphanumeric
  • 6 – Abbreviated
• NPI (Number Plan Indicator) for source (src_npi) and destination (dst_npi) represent the numbering scheme used for the clients. Common 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)
• session_type is used to specify the type of connection, and has to have one of the following values:
  • 1 – Transceiver
  • 2 – Transmitter
  • 3 – Receiver
  • 4 – Outbind

Once the connection has started, OpenSIPS can use it to exchange messages with its peer. The module will handle in the background all the SMPP protocol’s specifics.

SIP to SMPP gateway

When getting a text message from a SIP entity, it will be handled just like any other SIP request, by running the script. And if according your routing logic that message needs to end up to a SMSC, all you have to do is to call the send_smpp_message() method, specifying which SMSC should be used:

if (is_method("MESSAGE") && isflagset(TO_SMPP_TEST))
    send_smpp_message("SMPP_test");

SMPP to SIP gateway

When a message comes from a SMSC to OpenSIPS over SMPP, things get a bit more complicated – since SMPP messages are binary encoded, they can’t be sent directly to the script. Instead, they are translated to a SIP MESSAGE, and automatically sent to a SIP server or proxy, indicated by the outbound_uri parameter. Usually, the URI points to the same OpenSIPS instance, but note that the message will be sent over SIP – this means that it will be able to enter the script for determining its next hop, or final destination.

listen = udp:127.0.0.1:5060
...
# send all SMPP messages on loopback to the same instance
modparam("proto_smpp", "outbound_uri", "sip:127.0.0.1:5060")
...
route {
    ...
    if (is_method("MESSAGE") && $Ri == "127.0.0.1") {
        # handle message received over SMPP
        ...
    }
    ...
}

And that’s it, you know have a two-way gateway beween SIP and SMPP.

Conclusions

With only a few lines of configuration and the new SMPP module you can easily enhance your OpenSIPS-based VoIP platform with new means of sending text messages. Just give it a try and let us know if you ran into any trouble while setting up this feature!

Special thanks go to Victor Ciurel for developing and testing the new SMPP module in OpenSIPS!