ℹ️ The Auron SMS Server is now Auron Omni. Learn more here.

How can we help?

Setup a secure SMPP Server

This how to will guide you through all the steps of setting up a complete and fully functional secure SMS Center. An SMS Center accepts incoming SMPP connections and routes SMS messages through different providers using either GSM, HTTP or SMPP.

An SMS aggregator or SMSC works by finding the most cost effective route for its customers. Alternatively it can make sense to set up an SMSC to combine multiple low volume streams and have a central log or gateway directly to an SMS provider.

SMS Center - Overview

SMS Center – Overview

This how to shows just one way to set up an SMSC using Auron Omni. It is intended as a starting point to show you some of the Auron Omni capabilities and its incredible versatility. If you have a specific setup in mind but do not want to bother with the details of configuring Auron Omni please contact us. We can help you set up your project as well.

This SMS Center has the following features:

  • Secure incoming and outgoing connections using TLS
  • Any number of incoming SMPP connections
  • Any number or type of outgoing SMS channels
  • Supports Unicode and multipart messages
  • Does not store customer passwords
  • Highly customizable
  • Easy troubleshooting through comprehensive logging

Overview

The basics of setting up an Auron Omni configuration are about channels and triggers. The channels either connect to the outside world or allow the outside world to connect to Auron Omni. The triggers allow you to react to events. Triggers are small scripts that fire automatically on new messages or when a message changes state. In most cases Auron Omni can generate the script and you will not need to program anything.

In this how to you will learn the following things.

Set up and configure Auron Omni

To set up the SMS center and start testing you will only need the Auron Omni trial version. It is recommended to have a local instance of SQL Server Express available.

Ideally you would have a small SMPP client and SMPP server to test with. You could also let Auron Omni connect to itself but having these tools separate keeps your Auron Omni configuration more organized.

The SMPP Simulator from our freeware page is a great SMPP server for testing. As an SMPP client you can use any of the sample projects in the SMS Component. For convenience you can download the full runnable GUI sample project here. Please note that this sample runs only on a PC that has either the SMPP simulator or Auron Omni already present.

Following this how to requires a basic understanding of SQL and VBScript. No programming is required.

Installation

Follow these instructions to set up Auron Omni. For this how to please use the following settings:

  • Configure Auron Omni as stand alone or server
  • Connect to an existing SQL Server instance
  • Use database authentication
  • Run the service as the Local System user
  • Other settings are not important for this how to and can be left at their defaults

Create an SMPP Server Channel

Once Auron Omni is installed and configured please start Auron Omni Manager and follow these instructions to create a new SMPP Server channel. Make sure to modify the settings in the Server page, General Settings page and Advanced Settings page as follows.

SMPP Server Channel - Settings

SMPP Server Channel – Settings

In the Server page:

  • Use port number 2776. We use a non default port because this channel is secure
  • Allow both IPv4 and IPv6 connections
  • Listen on all available IP ports
  • Select a certificate from the local machine store

If you do not have a certificate available please follow these steps to configure a self signed certificate. The certificate is required to allow secure connections.

SMPP Server Channel - Disable Always Accept

SMPP Server Channel – Disable Always Accept

In the General Settings page:

  • Uncheck Always accept any bind request and Always accept any incoming SMS

By unchecking these options you will need to generate triggers that automatically verify bind requests and new messages. A bind request is an SMPP term for user login.

In the Advanced Settings page:

SMPP Server Channel - Store Password Hash

SMPP Server Channel – Store Password Hash

In this page make sure to check Store SHA1 of password. With this setting Auron Omni will never store the client password. Instead it stores a SHA1 hash.

You can leave other settings at their default values. After clicking Finish you should see the SMPP Server channel in the channel overview.

Manager - SMPP Server Channel

Manager – SMPP Server Channel

Connect for the first time

With the SMPP Server channel created you can use any secure SMPP client to connect to it, such as the SMPP client demo from the Auron SMS Component samples.

An SMPP connection is set up in two steps:

  1. Set up a secure connection
  2. Send a BIND request

The bind request in Auron Omni is just another message type. Like any message type it can trigger scripts automatically.

To use the SMPP client demo to connect follow these steps:

  1. Open demo.exe
  2. Click SMS via SMPP to open the SMPP client
  3. Set server to Localhost and port to 2776
  4. SystemID and password can be anything at this stage
  5. Click Connect

When clicking Connect you should see a new message of type SMPP Server Bind appear in the manager. You can open it by double clicking.

Your screen should now look like this:

 

Auron Omni Manager - Test bind timeout

Auron Omni Manager – Test bind timeout

This screenshot shows the SMPP client demo on the right side. The client is used to connect to the SMPP Server and the bind has timed out because we have not yet handled it.

The SMPP Server Bind message is only visible in the All view of Auron Omni Manager.

Storing SMPP Server users

Now that the SMPP Server channel is running we need to authenticate users. Before we can do that we need a place to store user data.

Auron Omni does not enforce a specific storage system. Instead it is designed to connect to your own backend system so your business rules apply without duplication.

For this how to we set up a table in SQL Server to hold user data. Open SQL Server Management Studio and run this SQL script:

CREATE DATABASE AuIntegration
GO

USE AuIntegration
GO

CREATE TABLE SmppServerUsers
(
		SystemID     NVARCHAR(16) PRIMARY KEY
	,	PasswordHash NVARCHAR(40)
	,	Credits      INT
)

This script creates the SmppServerUsers table used in this example. We use the credits field later.

Creating SMPP Server Users

Run the following script to insert two test users with 100 credits each:

USE AuIntegration
GO

INSERT INTO SmppServerUsers (SystemID, PasswordHash, Credits) VALUES
		(N'Test1', CONVERT(NVARCHAR(40), HASHBYTES('SHA1', N'Pwd1'), 2), 100)
	,	(N'Test2', CONVERT(NVARCHAR(40), HASHBYTES('SHA1', N'Pwd2'), 2), 100)

This stores passwords as SHA1 hashes. If you prefer plain text passwords you must uncheck Store SHA1 of password in the previous step.

The advantage of storing SHA1 hashes is that the actual password is never stored.

We use the SQL function HASHBYTES to create the hash and CONVERT to format it. For example the hash of Pwd1 looks like this: DC215545BA63D605FBCD647A9555270F566D918B

Technical note: If you use MySQL, PHP or another system make sure the SHA1 hash is generated from the UTF 16 LE version of the password string.

Create SMPP Server Bind trigger

Find more information about triggers and how to create triggers in Auron Omni here.

Next we create an SMPP Server Bind trigger.

Note: Like all generated triggers this is a template. You can configure it during creation and fully customize it afterwards.

Create SMPP Server Bind Trigger

Create SMPP Server Bind Trigger

In this case we name the trigger BIND with the description SMPP server bind. In the Select Channels page select the SMPP Server channel. On the SystemID Lookup page you can specify a data source for user lookup. Leave it empty to allow open access.

In this case we connect to our local database and use the table from the previous step. You can click the database icon to build and test the connection string.

After creating the trigger enable it by checking the box in front of it. In the manager it should look like this:

Auron Omni Manager - Bind Trigger

Auron Omni Manager – Bind Trigger

Test the SMPP server bind trigger

The SMPP Server bind trigger now processes all SMPP Server Bind messages. This means you can now log in to the SMPP Server.

You can test this again using the SMPP client demo.

It should now look like this:

Auron Omni Manager - Bind test OK

Auron Omni Manager – Bind test OK

To view trace details:

  1. Double click the SMPP Server Bind message
  2. Click the Trace tab

The trace shows that the BIND trigger succeeded and the bind was accepted.

Manage connected SMPP clients

To confirm the connection go back to the Channel view in Auron Omni Manager.

You will see a small 1 next to the online indicator of the SMPP Server channel:

1 Client Connected

1 Client Connected

This number increases for every active client session connected to the SMPP Server.

You can find more detailed information on the Manage SMPP Clients page of the SMPP Server channel properties:

  1. Open the Channels view in Auron Omni Manager
  2. Open channel properties using the pencil icon
  3. Go to Manage SMPP clients

 

SMPP Server - Manage Clients

SMPP Server – Manage Clients

This page shows all clients connected to the channel. In this case it is only the local host connection. Since both IPv4 and IPv6 are enabled the client connects using IPv6. The default bind type is Transceiver which means the client can send and receive SMS messages.

Accept messages and subtract credits

You may have noticed that it is still not possible to send SMS messages to the SMPP channel. If you connect using the SMPP Client demo and send an SMS you will disconnect after a few seconds. This is because incoming SMS messages are not yet accepted.

To accept messages we create an SMPP Server Acknowledge SMS trigger. This trigger can:

  1. Subtract one credit from the user
  2. Acknowledge the SMS or reject it if the user has no credits left

Note: Like all generated triggers this is a template that can be customized.

Create the trigger from the triggers view using the green plus icon.

Create SMPP Server Acknowledge Trigger

Create SMPP Server Acknowledge Trigger

We name the trigger ACK with the description SMPP server acknowledge. In Select channels choose the SMPP Server channel.

The Credits Lookup page defines where credits are stored. Leave it empty to always accept messages. Select a database to subtract credits automatically.

We connect to the local database and use the SmppServerUsers table.

In Auron Omni Manager the trigger view now looks like this:

Bind and Acknowledge Triggers

Bind and Acknowledge Triggers

Connect to the SMS provider

In this case we create one SMPP channel. However it could also be HTTP or GSM.

An SMPP channel is convenient for this test because it can connect to either the test and demonstration gateway or the SMPP Simulator.

If you create a new SMPP client channel in Auron Omni and keep default settings it will connect automatically to the test and demonstration gateway.

We name this channel SMPP1 with the description SMPP Channel. The two channels now look like this:

Auron Omni Manager - Channels

Auron Omni Manager – Channels

The SMPP Server channel (SMPP_SERVER1) is where clients connect. The SMPP client channel (SMPP1) is where we forward messages to.

Forward SMS and delivery reports

Forwarding SMS messages from SMPP_SERVER1 to SMPP1 is done with a trigger. We use the Forward trigger template.

We call this trigger FWD with the description Forward.

Forward Trigger - From SMPP Server to SMPP client

Forward Trigger – From SMPP Server to SMPP client

In Select Channels we select the From channel and the To channel. These are SMPP_SERVER1 and SMPP1.

Forward Trigger - Formatting

Forward Trigger – Formatting

In the Forwarded Message page you can keep default settings. The ToAddress and Body are copied from the original message.

About delivery reports

An SMS provider sends a delivery report when an SMS reaches its final status. This is typically Delivered or Rejected. In SMPP a delivery report is an SMS message with a status flag.

To receive delivery reports the original SMS must request them.

The SMS provider sends delivery reports only to SMPP clients. An SMPP client does not send delivery reports to an SMPP Server.

Forward delivery reports

Forwarding delivery reports is a two step process:

  1. Apply the delivery report on the outgoing channel
  2. Create a new delivery report on the SMPP Server channel

First create the Apply Delivery Report trigger.

Apply Delivery Reports

Apply Delivery Reports

This trigger sets the status of the original SMS to DELIVERED or NOTDELIVERED depending on the delivery report. We call it APPLYDLR.

You need to create this trigger for each outgoing SMS channel.

Finally create the SMPP Server Forward Delivery Reports trigger.

Smpp Server Forward Delivery Reports

Smpp Server Forward Delivery Reports

Create three versions of this trigger:

  • DELIVERED (FWDDLR)
  • NOTDELIVERED (FWDDLR2)
  • NOREPORT (FWDDLR3)

Testing bind and forward

Now that all triggers are in place the triggers view in Auron Omni Manager should look like this:

Auron Omni - Bind and Forward triggers

Auron Omni – Bind and Forward triggers

You can now send an SMS message to your SMPP channel using the SMPP client demo and it will be automatically forwarded. In the SMS view in Auron Omni Manager this looks like this:

Auron Omni Manager - Forward SMS

Auron Omni Manager – Forward SMS

The latest message is on top. To read events in order start from the bottom.

From bottom to top you will see:

  1. The original incoming message on SMPP Server Channel
  2. The forwarded message on SMPP Channel
  3. The delivery report on SMPP Channel which updates the status to Delivered
  4. The delivery report sent back to the originator on SMPP Server Channel

Route back from the SMS provider

In this how to we route messages from the SMS provider to SMPP users.

The channel SMPP1 is connected to the provider and SMPP_SERVER1 is where users connect.

We need to determine which message should go to which user based on the ToAddress field.

We store a recipient number for each SMPP Server user and use it for routing.

Update the SMPP users information

We extend the SmppServerUsers table to include a recipient number.

Open SQL Server Management Studio and run:

USE AuIntegration
GO

ALTER TABLE SmppServerUsers ADD AddressRange NVARCHAR(40)
GO

We store the recipient number in AddressRange.

Run this script to update existing users:

USE AuIntegration
GO

UPDATE SmppServerUsers SET AddressRange = '+31699887766' WHERE SystemID = N'Test1'
UPDATE SmppServerUsers SET AddressRange = '+31688776655' WHERE SystemID = N'Test2'
GO

Create a new forward trigger

We now add a new forwarding trigger from a template. In this case we edit it afterwards.

Open the triggers view in Auron Omni Manager and click the green plus icon. Select Forward Trigger Template (VBScript).

Forward from SMS Provider to sMPP Server

Forward from SMS Provider to SMPP Server

Call this trigger RECVFWD with the description Forward. The From channel is SMPP1 and the To channel is SMPP_SERVER1. Keep default settings.

Edit the forward trigger

We now edit the trigger so it routes messages to the correct user.

To edit RECVFWD click the pencil button. Select the VBScript tab.

Edit Forward Trigger Script

Edit Forward Trigger Script

Click the pencil icon next to the script path.

To make this work we set the BillingID property based on the SystemID from the SmppServerUsers table.

This is the first change:

' // ========================================================================
' // Forward
' // ------------------------------------------------------------------------
' // Automatically forward this message
' // ========================================================================
Function Forward(objMessageIn, objMessageDB)

    Log ">> Forward"

    ' -- Find the billing ID
    ' Add this block until the line that starts with ' ---
    sBillingID = FindBillingID(objMessageIn, objMessageDB)
    If sBillingID = "" Then
      objMessageIn.AddTrace "Could not find a matching address range"
      objMessageIn.StatusID = g_objConstants.MESSAGESTATUS_FAILED
      Log "<< Forward"
      Exit Function
    End If
    ' ---

    ' forward SMS message
    Set objMessageOut = objMessageDB.Create("SMS")
    objMessageOut.AddTrace("Forward message from channel: [" & _
      objMessageIn.ChannelID & "]")
    
    ' -- Set the billing ID; copy this next line
    objMessageOut.BillingID = sBillingID

    objMessageOut.ConversationID = objMessageIn.ID
    objMessageOut.ChannelID = "SMPP_SERVER1"

    ' ... - rest of the function

This part of the Forward function in the RECVFWD script needs two small changes.

  • Copy and insert the block starting with Find the billing ID
  • Insert the BillingID line after it
  • Make sure it is placed correctly in the function

The last change is:

Function FindBillingID(objMessageIn, objMessageDB)

  FindBillingID = ""
  
  ' The address range must match the ToAddress exactly
  sQ = "SELECT SystemID FROM AuIntegration.dbo.SmppServerUsers WHERE AddressRange='" & _
       objMessageIn.ToAddress & "'"
  Set objRs = objMessageDb.AdoConnection.Execute(sQ)
  If Not objRs.EOF Then
    FindBillingID = objRs("SystemID")
  End If

End Function

Copy this block after End Function in the script.

Save the script using File and Save.

Finally

Your final setup now has 8 triggers that define the behavior of your SMSC.

This is what the triggers view should look like:

Auron Omni Manager - All Triggers

Auron Omni Manager – All Triggers

You have now configured your very own SMS Center.

All of these triggers can be freely modified to customize the behavior to your specific requirements.