Ozeki 10 SMS Gateway

SMS routing

This document gives you an introduction to SMS routing. It covers the basic concepts of the SMS routing procedure in Ozeki 10 SMS Gateway. You will learn about the routing table, you will find out what a routing rule is and you will get simple routing examples. More advanced examples and more information are available in the SMS routing for SMS service providers guide, the how to copy and forward sms text messages to multiple destinations guide and in the least cost sms routing guide. If you wish to modify the telephone numbers and the messages text during reading, pleas visit the how to modify an SMS message on the fly page.

What is SMS routing?

SMS routing is the procedure used by Ozeki SMS Gateway to decide where an SMS text messages should be forwarded to. SMS routing is based on pattern matching and it allows messages modification. SMS routing solutions are used by SMS service providers and large organizations.

What is SMS routing?
What is SMS routing?

How to configure SMS routing (Quick instruction list)

To configure SMS routing you need to launch the Ozeki SMS App and you need to open the routing table by clicking on the "Routes" toolbar button.

routing table in the routing table screen
Figure 1 - Routing table in the SMS gateway.

To configure SMS routing follow these quick steps:

  1. Open Ozeki SMS Gateway on the windows Desktop
  2. Login with the username "admin"
  3. Open the SMS Gateway app
  4. Find the toolbar in the top
  5. Find the "Routes" toolbar button
  6. Click on the "Routes" toolbar button
  7. This will bring up the routing table
  8. Click create new route to create an SMS route
  9. Fill in the route creation form
  10. Click OK to create the new route
  11. Use the red and green arrows to move the rule into position

What does SMS routing do?

Routing assigns a "To connection" to the message. In other words it selects the destination connection where the message should be forwarded to. In Ozeki 10 everything is a "Connection". A connection is a messaging endpoint, that can send and receive a message. Although connections are displayed in groups (e.g.: sms users, mobile network links, etc), they are still identical connections when it comes to routing.

The SMS routing is the procedure that is used to decide where an SMS message should be forwarded to. This procedure is execute when an input messages is sent to the routing table (Figure 2). The routing table executes the routing algorithm and returns an output message, that is identical to the input message, but it has a "To connection" assigned to it. After the routing procedure the output message is forwarded to the "To connection".

Figure 2 - The SMS route select the destination

What is an SMS routing rule?

The SMS routing table consists of routing rules. A routing rule has a match condition, a modifier command set and a destination. When an SMS is sent, it is first passed to the routing table, where it is matched against routing rules. If a rule "matches" the SMS, it executes the modifiers and forwards the message to the destination. Matching is done based on configured conditions, such as sender connection, sender phone number, messages text, service period, etc. Modification rules are only applied if the SMS passes the match conditions. If the match conditions don't fit, the next routing rule is tried in the routing table.

Figure 3 - What is an SMS rule

How are SMS routing rules executed?

For each message that is sent, the routing table is executed. The execution id done top down: If a rule matches the destination ("To connection") is assigned and routing stops. The message is forwarded to the selected to destination.

Figure 4 - SMS rule execution order

How is the routing table displayed?

If you open the home screen, you will see two views of the main routing table. On the top you find a filtered table, that only displays the "inbound routes", and in the bottom you see a filtered table that only displays the "outbound routes". In practice we call a route inbound route, if the "From connection" is classified as an SMS network connection. Everything else is an outbound route.

Figure 5 - SMS routing table filtered to home

This distinction is done, because most users think in terms of inbound and outbound routes. Even though there is no difference between such rules in the ozeki routing system, it is better to present the routing table this way. People understand it better if routes are organized by their sender connection ("From connection") into groups and only these filtered groups are presented. If you want to become a routing expert always use the main routing table instead of the filtered views, because it gives you a better sense of what happens to a certain message.

routing table in the home screen
Figure 6 - Routing table in the home screen.

How can I create a routing rule?

If you want to create a routing rule, open the main routing table by clicking on the "Routes" toolbar button, and click "Create new Route". This will bring up the route creation form. Notice the "Match" and "Modify" tabs in this form. These are the tab pages where you can define match condition and modification commands.

click on 'create new route'
Figure 7 - Click on "Create new Route"

What if I don't see my connection?

Large SMS systems can have a very larg number of connections. To simplify life the offered "From" and "To" connections are filtered by default. Rarely used connection are hidden. This can lead to the fact, that you don't find your connection in the list.

If you can't see the connection you wish to work with in the "From" or "To" list, simply click on the Cog button in front of the combo box holding the list of connections. This will open a dialog, where you can select other connection types to be presented in the list.

click on the cog to find additional connections
Figure 8 - Click on the Cog to find additional connections

Default SMS routing (Example 1)

Before we jump into complex routing configurations, it is a good idea to understand the default routing table. In the default routing table you will see two routes: out_sms and in_admin. The out_sms route is used to forward messages from so called "SMS users" to "SMS connections". "SMS connections" are a group of connections that are used to connect your system to the mobile network. The in_admin user is an automatically create rule to forward a copy of each incoming SMS to the admin user. You might notice the "Copy" mode in the routing table. More information about how to send a copy of an SMS to a certain user can be found in the how to forward an incoming SMS to multiple destinations guide.

To understand how the out_sms route works, we create two SMPP SMS client connections to two different mobile network operators. We will call these connections SMPP_client_1 and SMPP_client_2. (In this example we will not modify the default routing table). We will send an SMS from the admin user, by clicking on the "New" button in the toolbar. In this setup an SMS from admin will go out on SMPP_client_1 or SMPP_client_2. The system will randomly select the first available SMS connection from the outgoing message. The route used is the "out_sms" route, which forwards SMS from "Any_SMS_User" to "Any_SMS_Connection".

default route highlighted in the routing table screen
Figure 9 - Default route highlighted in the routing table screen.

When the default route is used the SMS sent by admin is forwarded by the route called "out_sms"

Figure 10 - Randomly select the mobile network

It is worth mentioning that this random route selection is not exactly random. In fact a load balancing algorithm distributes the load among the mobile network connections with free capacity taking into account the previously measured capacity of each connection.

SMS routing by source (Example 2)

The next example shows how SMS routing can be used to assign a fix destination to a specific source. In our example we want all SMS messages sent by admin to go out on SMPP_Client_1. This setup is very often used, because it is often a requiremetn for a user to always use a specific mobile network connection. To achieve this we can create a simple source to destination route.

To demonstrated how this setup works, we can the same number of connections used in Example 1. We can add an extra route to our routing table that will forward SMS from admin to SMPP_Client_1. The route will make sure that an SMS from admin will be forced to go out on SMPP_client_1. In this configuration the SMPP_client_2 will not be used at all.

route of sms going to +3611111111 in the routing table screen
Figure 11 - Route forcing sms from admin to smpp client 1.

sms from admin is always forwarded to smpp_client_1
Figure 12 - SMS from admin is always forwarded to SMPP_client_1

SMS routing by phone number prefix (Example 3)

The next example demonstrates how SMS routing can be done based on phone number prefixes. This is a common task because often you want to send certain messages belonging to a network identified by a phone number prefix to certain connection. For example if you would like to route SMS aimed at Hungary you would route SMS messages sent to prefix +36.... to the Vodafone Hungary network. You could also setup a second rout routing prefixes +44.... to the T-Mobile network in the UK.

The following figure demonstrates how you can define a phone number prefix as an match condition. The example uses a pcre typ regular expression. This expression is used to match the recipient address ("To phone number") do decided whether the route should be applied or not.

create new routing rule for sms routing by phone number prefix
Figure 13 - Create new routing rule for SMS routing by phone number prefix

set prefix for SMS routing
Figure 14 - Set prefix for SMS routing

'+36.*' goes through route 'hungary' to smpp_client_1
Figure 15 - "+36.*" goes through route "Hungary" to SMPP_client_1

SMS routing by full phone number matching (Example 4)

If you own a set of phone numbers, you can assign a unique phone number to your customers or users. In this case you will want to route incoming SMS messages sent to a particular phone number to a particular user. Example 4 shows the routing configuration to achieve this goal.

In this example we add two HTTP users: http_user_1 and http_user_2 who will receive the incoming messages. One will be assigned phone number +3633333333, the other will be assigne phone number +3644444444. We now create two routes with full phone number matching. These routes will forward any SMS sent to these phone numbers to the appropriate users.

route of sms going to +3633333333 in the routing table screen
Figure 16 - Route of SMS going to +3633333333 in the routing table screen.

As you can see in the figure above, the "From" field is set to "Any_SMS_Connection". This is because we want all SMS messages sent to phone number +3633333333 to be routed to http_user_1 regardless of which SMS connection do they arrive. The destination ("To") for this route is fixed to http_user_1. If you look at the figure below you will see, that in this case we specify the full phone number in the recipient matching condition. Noticat that we do not put the slash (/) in front of and after the phone number. This is because we do not perform a regular expression pattern match in this case. We simply do a strict phone number comparison.

set full phone number for matching to +3633333333
Figure 17 - Set full phone number for matching to +3633333333.

The configuration for http user 2 is very similar. The difference is the destionation ("To") field and the phone number put into the "To address" groupbox on the "Match" tabpage of the routing rule. You might also notice that these two routes will be called route_3 and route_4.

route of sms going to +3644444444 in the routing table screen
Figure 18 - Route of SMS going to +3644444444 in the routing table screen.

If you work with many routes, it is a good idea to add meaningful names to routes, so you can identify them quickly. There are better names, then the default route_3 or route_4 used in this example.

set full phone number for matching to +3644444444
Figure 19 - Set full phone number for matching to +3644444444.

incoming sms sent to +363333333 is routed to http_user_1
Figure 20 - Incoming SMS sent to +363333333 is routed to http_user_1

SMS routing by keywords (Example 5)

The next example deals with SMS routing based on keywords in the message text. This features is often used in quiz games, SMS voting or keyword based content lookup services. In this example we route any SMS coming from Any_SMS_Connection containing the word "vote" to http user 2.

route any sms containing the word 'vote' to http user 2
Figure 21 - Route any SMS containing the word "vote" to http user 2.

By looking at the next Figure, you might notice that we use regular expression matching. In this regular expression pattern (also called as regex pattern), we put a .* pattern in front of and after the word. This tells the regex engine that the keyword "vote" can be anywhere in the messages. This connediton will match the following SMS texts: "Hello, here is my vote: red" or "vote red" or "I am not voting".

You may also consider putting in the case insensitive modifier called "i" which stands for ignor case if you expect that the keyword will be sent as either lower case or upper case. The pattern "/.*vote.*/i" would match "vote", "Vote", "VOTE" or "vOtE".

set message text prefix for receive sms for http user 2
Figure 22 - Set message text prefix for receive SMS for http user 2.

SMS routing by text and time period matching (Example 6)

It is useful to know that there is also a service period matching condition available, that can be used to limit the lifetime of this rule. This combination: text keyword matching and service period are often used together for SMS content services that operate for a given time period. In this example we route any SMS coming from Any_SMS_Connection containgin the word "vote" between 2021-04-01 00:000:00 and 2021-04-30 24:00:00 to to http user 2.

Figure 23 - Route any SMS containing the word "vote" in the service period 2021-04-01 00:000:00 and 2021-04-30 24:00:00 to http user 2.

set message text prefix for receive sms for http user 2
Figure 24 - Set message text prefix for receive SMS for http user 2.

set service period form for receive sms for http user 2
Figure 25 - Set service period form for receive SMS for http user 2.

Further reading on SMS modifier commands

The above examples demonstrated SMS matching conditions. Another strong feature is called SMS moficiation during routing. The idea is that once an SMS is matched against a rule, the SMS can be modified. This feature is very useful, because it not only allows you to be in control of all the messages that pass through your system, but you may also fix certain errors, such as incorrent destination numbering or you may black list certain unacceptable content. The following documents povide information on modifying SMS content.