SMS switch manual

The SMS switch is part of the 5gVision suite of products that also includes routing, billing, monitoring, and log collection and can provide a complete SMS switching and management solution with practically unlimited routing capabilities.

This product is not based on any open source code, with the SMPP stack fully written by our development team, which lays a solid foundation to any future enhancements and modifications. The full switch and billing architecture consists of the following main components:

• The switching module that writes all incoming SMSes to the DB to ensure their delivery even if a switch restart is performed, processes SMSes from the DB, runs the routing procedures, sends SMSes to vendors, and generates CDRs.
• If the built-in static routing is not covering your needs, you may use an external dynamic SMS routing module with LCR, profit-, quality-, and %-based routing managed by formulas, and a possibility to create expressions to temporarily block gateways. It is also possible to block a Customer or a Vendor on reaching a certain balance.
• The external routing instance generates a list of routes to try and sends it to the SMS switch. One switch can work with multiple routing instances, thus providing for redundancy and smooth upgrade and restart procedures. The routing also provides rates that the switch writes to CDRs.
• A flexible and powerful Rate management system is used to import and manage vendor and customer rates.
• A billing module handles accounting, payments, CDR rating and re-rating, and invoice generation.
• Our generic VoIP/SMS Monitoring system collects statistics for reports and quality-based routing and provides comprehensive monitoring and alerting tools.

The switch also has an HTTP API to receive and send SMS messages (please see HTTP API).

The SMS Gateways table contains connection settings for all gateways used in your system. There can be 2 types of gateways which differ in a connection mode on our side:

• Client - we are a Client and create a connection to a partner GW.
• Server - we are a Server and wait for a connection from a partner GW.

Depending on the connection mode, the system takes into account the corresponding network parameters for a gateway. The system disables unnecessary fields when you choose one of the modes. If the connect mode is Server, then only the parameters ended with Server are considered. Own IP:port we're Server is chosen from the Drop-down table linked to the child table Switch IPs containing a list of own SMS switch IP:port:protocol records to accept incoming connections from partners. The protocol are smpp or http, the latter is used for receiving SMSes over HTTP API. You can add/edit/remove records right in the drop-down table. If the connect mode is Client, then the parameters ended with Client are used. The Transc. mode parameter is also applicable only if we are Client and allows to enable/disable initiation of a transceiver mode for binding.

Username and Password are used in both modes: to login to a partner GW if we are a Client, or to authorize a partner GW if we are a Server.

You can use the C button on the top menu or right-click a table header to display some additional parameters. For instance, the Client protocol column allows you to select what protocol to use for SMS sending if we are a Client, smpp or http. If you need http, then you have to fill up the HTTP URI we're Client field (please see HTTP API).

You may execute some translations on the gateways level:

• IN SRC/DST number translation - regexp for SRC/DST number translation BEFORE routing, translated part goes after "/", groups are "\\1", "\\2", etc., for example: 123(.*)0(.*)/456\\1\\2.
• OUT SRC/DST number translation - regexp for SRC/DST number translation AFTER routing, translated part goes after "/", groups are "\\1", "\\2", etc., for example: 123(.*)0(.*)/456\\1\\2.
• IN + trans. - whether to translate + sign in front of numbers into ToN=International on incoming SMSes.
• OUT + trans. - whether to translate ToN=International into + sign in front of numbers on outgoing SMSes.

If you need to limit incoming or outgoing SMSes on a GW, there are special TPS parameters: Cust. TPS and Vend. TPS. TPS - maximum SMSes throughput per second. It is calculated on the basis of EMA (Exponential Moving Average) similar to EMA used in the VoIP statistics module. But instead of the adaptive EMA window the SMS Switch uses explicitly specified Cust./Vend. TPS time - a scale of the EMA smoothing in seconds. The more TPS time, the slower EMA value growth, and the slower reaction of the system to SMSes exceeding. Actually, the system allows exceeding of the configured TPS for time less than the specified TPS time. By default, Cust./Vend. TPS time is 10 sec.

Force DLR request forces an SMSC DLR request even if an incoming SMS doesn't require it.

There is a group of special Bind parameters (like Client system type, Server system id, and so on). They allow you to tune some settings for binding with a partner GW. Parameters starting with Client or Server, are meant only for the Client or Server modes. Otherwise, a Bind parameter works for both modes. You can find a detailed description in the Bind parameters section.

You have a possibility to assign a dedicated routing instance to a gateway via the Routing field. It is linked to the Routing servers table where all available routing instances are stored. In this case all messages from the GW will be routed by a chosen routing instance.

After configuring SMS Gateways, you can setup a simple static routing in the SMS Dialpeers table. This is a default built-in routing used in the SMS Switch, but it does not support LCR or quality-based routing.

If you need more advanced dynamic routing on basis of cost and quality, please contact 5gVision support to setup it on your system. It will require several additional 5gVision modules: separate dynamic SMS/VoIP Routing, Rate management to upload vendor rates (plus customer rates if you need to route on profit), Monitoring to collect statistics for quality-based routing.

The SMS Switch can work in different routing modes at the same time, for instance, it can use the built-in static and an external dynamic routing. Routing instances are listed in the Routing servers table.

The SMS Dialpeers table had the following mandatory columns that you need to fill:

• Dialpeer name - just a name for your reference.
• Gateways out - one or several gateways from the drop-down table to send messages to.
• Priority - the less the priority value - the higher a place of the dialpeer is in the routing list.

The Sort method for new dialpeers is No sort by default, but you can select Round robin mode if there are several OUT gateways. If you need to disable a dialpeer please use the Status checkbox.

There are parameters that allow you to filter dialpeers by several criteria:

• Gateways IN allowed - choose the IN gateways this dialpeer can route traffic from.
• SRC/DST codes allowed/denied - enter SRC/DST number prefixes allowed/denied.
• SRC/DST MCC/MNC allowed/denied - choose SRC/DST MCC/MNC numbers allowed/denied from the drop-down table of MCC/MNC names.

Although it is uncommon to translate numbers in the SMS world, you may use SRC/DST number translations fields if required, for example for test purposes.

SRC/DST TON and SRC/DST NPI allow you to overwrite TON (type of number) and NPI (numbering plan identification) when an SMS hits this dialpeer.

Every received message is stored in the DB. If an SMS sending was failed and retransmits are not prohibited for a gotten error in the Error codes table, then the SMS switch will keep trying to send the message at regular intervals until it is successful or the retransmit timeout is over. The regular retransmit interval is configured globally for the SMS switch and equals 10 min by default.

There are several parameters which affect the resulting retransmit timeout:

• validity_period field from the message - taken from the submit_sm of the SMS.
• Validity period parameter from the GW config - see Bind parameters.
• Default validity period for the SMS switch - configured globally for the SMS switch and equals 1 day (24*60*60 sec) by default.

At first the system tries to find the smallest value from validity_period field from the message and Validity period parameter from the GW config. If both of them are empty, Default validity period for the SMS switch is taken into account.

For SMS Routing you need an MCC/MNC database. In the 5gVision SMS Switch this information is stored in 2 tables: MCC/MNC names and MCC/MNC codes.

The MCC/MNC names table stores information on which mobile operator and country a certain MCC/MNC number belongs to. You can find the Association of phone number prefixes to MCC/MNC numbers in the MCC/MNC codes table. These tables already contain some default data but it can be updated anytime on request.

The SMS CDRs module is similar to the standard CDR module of the Monitoring and Alerting product where you can view, sort, filter, share, and export SMS switch CDRs. Delivery statuses are shown in CDRs as well, even if DLRs are recieved hours after an SMS was sent.

The Gateway status allows you to control the connection status of configured SMS gateways.

This table stores the list of error codes with which an SMS sending can be completed. The SMS switch loads the default codes there but you can edit them and add your own. Some vendors send nonstandard error codes and in order to display them properly in the Error code field of the SMS CDRs you need to include these codes to the list. The table consists of the following columns:

• Code - standard codes - 4 bytes, nonstandard codes - 5 bytes and more.
• Code name - standard codes starts from ESME_, local nonstandard - LOC_. This name is displayed in the Error code field of the SMS CDRs.
• Comment - extended description of the code.
• Stop route - if it's enabled and the SMS switch gets this error when attempting to send a message, it stops on the current route and doesn't try others.
• Stop attempts - if it's enabled and the SMS switch gets this error, it stops attempting to resend the message at all.
• Translate - allows to translate a nonstandard code to a standard one to send to the Client in submit_sm_resp. If it is empty, the code is translated to 255 ESME_RUNKNOWNERR.

The SMS switch supports HTTP API for receiving and sending SMSes.

If you need to send a message to your SMS switch over HTTP API for further processing and routing, you should form a standard HTTP request, for example, using a Web browser. The URL should look like this:

http://192.168.10.100:2777/sendsms?username=5gvision&password=5gpass&to=0123456&text=5gVision+rocks!

The parameters that can be used in the URL are as following:

• username (string) - Username or account name.
• password (string) - Password associated with a given username.
• from (string) - Phone number of the sender.
• to (string) - Phone number of the receipient.
• text (string) - If the contents will not fit into a maximum message size according to the currently set coding, a message will be cut into several messages.
• charset (string) - Charset of text message. Used to convert the text to a format suitable for 7 bits or to UCS-2. Defaults to UTF-8 if coding is 7 bits and UTF-16BE if coding is UCS-2.
• mclass (number) - Optional. Sets the Message Class in DCS field. Accepts values between 0 and 3. A value of 0 sends the message directly to display, 1 sends to mobile, 2 to SIM and 3 to SIM toolkit.
• mwi (number) - Optional. Sets Message Waiting Indicator bits in DCS field. If given, the message will be encoded as a Message Waiting Indicator. The accepted values are 0,1,2 and 3 for activating the voice, fax, email and other indicator, or 4,5,6,7 for deactivating, respectively.
• coding (number) - Optional. Sets the coding scheme bits in DCS field. Accepts values 0 to 2, for 7bit, 8bit or UCS-2. If unset, defaults to 7.
• validity (number, minutes) - Optional. If given, the SMS switch will try to send the message for this many minutes. If the destination mobile is off or there is another situation that it can't receive the SMS, the SMS switch discards the message.
• deferred (number, minutes) - Optional. If given, the SMS switch will postpone sending of the message by these many minutes from the current time.
• pid (byte) - Optional. Sets the PID value.
• priority (number) - Optional. Sets the Priority value (range 0-3 is allowed). Defaults to 0, which is the lowest priority.

To be able to send an SMS via HTTP you should add a GW in the SMS Gateways table with the Server Connect mode and a corresponding Username/Password. The field Own IP:port we're server has to contain a Switch IPs record where the protocol is http or to be empty.

You will get HTTP 202 response if the SMS was sent successfully, and HTTP 404 if there was an error.

If you want your SMS switch to send SMSes by http protocol, you should configure the Client protocol and HTTP URI we're Client fields for a GW (Client mode) in the SMS Gateways table. The Client protocol should be changed to http and HTTP URI we're Client should be filled in with a URI string which will be used to form an HTTP request sent to a server. For example:

http://partnersmsservice.com/send.php?login={{username}}&psw={{password}}&phones={{dst}}&charset=utf-8&mes={{message}}

The URI string can contain these keywords to be replaced by real values:

• {{message}} - message body.
• {{src}} - source number/alias.
• {{dst}} - destination number/alias.
• {{username}} - login taken from the Username field of the GW config in the SMS Gateways table.
• {{password}} - password taken from the Password field of the GW config in the SMS Gateways table.

There are a couple of additional parameters hidden by default:

• Msg complete timeout - the SMS switch concatenates parts of a message if they are transferred in several SMSes. This parameter allows you to setup a timeout within which we wait for all parts of the message. Default value is 30 sec.
• HTTP encoding we're Client - by default we send a message body in an HTTP request encoded in UTF-8, which is standard for international HTTP URI. If a server waits for a messages body with another encoding, then you may setup it in this parameter. The list of supported encodings is available here: https://docs.python.org/2/library/codecs.html#standard-encodings.

For Bind parameters description we need to give several definition from SMPP v3.4 specification:

• SMSC - Short Message Service Centre. Actually, this is an SMPP Server entity.
• ESME - External Short Message Entity. This is an SMPP Client, like Voice Processing Systems, WAP Proxy Servers or Message Handling computers. It excludes SMEs.
• SME - Short Message Entity. This is a mobile station located within the Mobile Network.

The list of Bind parameters supported by the 5gVision SMS switch is as follows:

• Client system type - used to categorize the type of ESME that is binding to the SMSC. Examples include "VMS" (voice mail system) and "OTA" (over-the-air activation system). Specification of the client system type is optional - some SMSC may not require ESME to provide this detail. In this case, the ESME can set the client system type to NULL.
• Client service type - can be used to indicate the SMS Application service associated with the message. The following generic client service type are defined:
  • ““ (NULL) - Default.
  • CMT - Cellular Messaging.
  • CPT - Cellular Paging.
  • VMN - Voice Mail Notification.
  • VMA - Voice Mail Alerting.
  • WAP - Wireless Application Protocol.
  • USSD - Unstructured Supplementary Services Data.
  All other values are carrier specific and are defined by mutual agreements between the SMSC Service Provider and the ESME application.
• Client address range - used to specify a set of SME addresses serviced by the ESME client. A single SME address may also be specified in the client address range parameter. UNIX Regular Expression notation should be used to specify a range of addresses. Messages addressed to any destination in this range shall be routed to the ESME. For IP addresses, it is only possible to specify a single IP address. A range of IP addresses is not allowed. IP version 6.0 is not currently supported in this version of the protocol.
• client bind addr ton - defines the Type of Number (TON) in the decimal format to be used in the SME address parameters.
  • Unknown - 0
  • International - 1
  • National - 2
  • Network Specific - 3
  • Subscriber Number - 4
  • Alphanumeric - 5
  • Abbreviated - 6
• Client bind addr npi - defines the Numeric Plan Indicator (NPI) in the decimal format to be used in the SME address parameters.
  • Unknown - 0
  • ISDN (E163/E164) - 1
  • Data (X.121) - 3
  • Telex (F.69) - 4
  • Land Mobile (E.212) - 6
  • National - 8
  • Private - 9
  • ERMES - 10
  • Internet (IP) - 14
  • WAP Client Id (to be defined by WAP Forum) - 18
• Client msg id type - in SMPP protocol an SMS response (submit_sm_resp) and a DLR (deliver_sm) are bound by a message_id and receipted_message_id accordingly. They can contain ID as a string or as a number. The number may be in the decimal or hexadecimal format. This parameter allows you to setup the conversion of the number format for these IDs. By default there is no the conversion.
  • 0 - deliver_sm dec, submit_sm_resp dec
  • 1 - deliver_sm dec, submit_sm_resp hex
  • 2 - deliver_sm hex, submit_sm_resp dec
  • 3 - deliver_sm hex, submit_sm_resp hex
• Enquire link interval - specifies the interval of checking availability of the active session by enquire_link messages.
• Max pending submits - maximum number of SMSes with no answer (no *_resp). If there are SMSes to send more than max pending submits, then the excessive SMSes will be waiting in the queue. Default value is 50.
• Wait ack - waiting time of answers (*_resp) to SMPP requests. If there is no answer during this time, the message becomes expired. For instance, if we don't receive submit_sm_resp for submit_sm within a wait ack period, then the message is supposed unsent. Default value is 60 sec.
• Server system id - provides an identification of the SMSC to the ESME at bind time.
• Validity period - maximum time in seconds while the SMS switch tries to send a message. Every SMS contains its own validity period. This parameter allows you to set an upper limit.
• Server max pending requests - maximum number of unanswered queued incoming requests. It allows you to protect from the flood. By default it is 30000 for every ESME.
• Server max request time - maximum time while the SMS switch keeps an unanswered incoming request in the queue. It restricts a processing time for an incoming request (SMS, DLR) and guaranties a response within the specified interval. Default value is 300 sec.