1.9.2 Outbound SMS

The SMS flow in voipswitch divides on the traffic from client to voipswitch and then from voipswitch to destination network – usually an SMS provider or an SMS gateway.

SMS can be sent by the retail and wholesale client types. The retail clients make use of the SIP method MESSAGE, same as for the Instant Messaging. The wholesale clients can use SIP, SMPP and HTTP protocols for sending the messages to the voipswitch.

For sending messages out from voipswitch to destination network the following protocols can be used:

• SIP
• HTTP
• SMPP

When a message comes to voipswitch it first checks in the Routing plan if the message’s destination is a retail client. If not the message is sent over http protocol to the SMS Web API address defined in the Settings/System/WebAPIs SMS Web API – Voipswitch field.

The URL should be as follows:

http://yourdomain/VSServices/SendSms.ashx?login=!LOGIN!&pass=!PASS!&text=!TEXT!&from=!FROM!&to=!TO!

The exact URL may differ depending on your deployment. By default the API is in the VSServices folder.

The VSServices route SMSes based on the SMS routing plan which associates SMS providers with prefixes. External SMSs are charged according to the SMS tariff assigned to the client account.

The successfully delivered messages are saved into the voipswitch.sms_outbox table. Their costs are stored in the calls and calls_costs tables. They can be viewed in the VSM Reports/CDR menu and VUP/VUC. The SMSs are distinguished from the calls records by the route_type attribute 8 and the id_cc which for SMSs always ends with 99, e.g. 1799.

SMS tariff

Tariffs on voipswitch consist of separate rates for calls and SMS. How to create a tariff is described in the Billing chapter. If you want to check if a tariff contains rates for SMS go to the Billing/Tariff/Tariff menu, click on a particular tariff and then, in the Rates tab, choose the SMS from the drop down component on the left to the prefix field and click Search button.

The list of prefixes with associated rates should appear.

SMS providers

The SMS traffic can be sent to SMS providers (carriers) or to an SMS server or gateway. Both types can be added in the Routing/SMS/Providers menu.

When adding a new provider you will be asked to enter the required data. They can be changed later in the edit mode.

The common properties for a provider include:

• Name - a name under which a provider will be visible in the SMS routing plan and CDRs
• Calculate costs - when ticked voipswitch calculates the cost of SMSs according to the cost tariff chosen for the provider. The tariff can be picked from the drop down list showing all available tariffs. Make sure you select the one with the cost rates which you pay to the provider. The costs are shown in the administrator’s CDRs and are used in Reports.
• Active – if not checked on the system will skip this provider in the SMS routing plan

Provider type option allows to choose the protocol used for communication. It can be HTTP, SMPP or SIP. Depending on which protocol is chosen a different set of configuration fields will appear.

SIP

• Server – the IP or FQDN of the destination SIP server
• Port – the port on which the server’s listeners is running
• Login – SIP username
• Password – SIP password
• Display Name – the SMS sender name or number, it is sent in the SIP FROM header

HTTP

For an HTTP provider a connection string has to be defined. The string is an URL with certain parameters which will be passed with the request.

In the example on the picture the URL’s address is:

http://178.255.40.65/VSServices/SendSms.ashx

and the parameters are:

The values of the from, to and text parameters should be replaced with the values from the original message received from a client. To do so use the variables as in the table above. When a new message comes in voipswitch will copy the values to the appropriate parameters in the connection string.

The strings will differ as not only the address will be different but also a provider may use completely different parameter names. Make sure that the variables are put into proper parameters.

SMPP

For the SMPP protocol the following fields have to be configured:

• Server address - IP or FQDN of the provider
• Port – port of the SMPP listener
• Send as Unicode – messages will be converted to Unicode character set
• Login - username required for authentication with the SMPP service (given by the provider)
• Password – required for authentication with the SMPP service (given by the provider)

There are additional SMPP parameters Npi, Ton, Dest. Npi, Dest. Ton, Authorized Id. Please check with your provider if they are required and if so what values should they have assigned.

In most cases when a destination provider uses the SMPP protocol it may be required to uncomment and set up the sms_smpp_waittime parameter to 10000 (10 sec) for VSServices in the Web.Config file (default path "c:\inetpub\wwwroot\VSServices") 

SMS routing plan

The routing for external SMSs can be configured in the Routing/SMS/Routing plan menu.

Note: the SMS routing plan applies only for external SMSs. Internal Instant messaging (IM) uses the main Routing/Routing plan.

The VSServices checks the SMS routing plan in order to find the best matching entry for the number from the TO field. If found the message will be converted to the protocol used by the route and then sent to the destination provider.

Below picture shows an entry from the SMS routing plan.

• Prefix – a destination number or more general prefix, the VSServices will use this field when looking for the best matching entry
• Priority - the priority of the route. The lower the number, the higher priority. If an SMS cannot be sent to the destination with the priority 0 (an error is received or timeout occurs) the VSServices will try the one with the priority 1, and so on.
• Balance share - allows setting a percentage share for messages being routed to different providers using the same prefix.The following three requirements must be fulfilled for valid configuration of this feature:
  • prefix is exactly the same for each entry
  • priority is exactly the same for each entry
  • sum of the balance share value for all entries with the same prefix must equal 100
• Do not jump - if ticked the routing function does not jump (re-routes) to the next matching route (provider) when SMS delivery has failed
• Rules for modifying client's data - enables manipulating destination number and sender name before they are sent to the provider.
• Cost tariff rule - modifies the destination number before it is used for calculating the cost according to the cost tariff. The modification is only for billing, the modified number is not sent to the destination

Note: the Cost tariff rule applies only for calculating the cost which is stored in the CDR related tables. The modification is not reflected in the user charging function.

• Special properties – default set to none. Other options:
• • Prefix not allowed – choose this option if you want to exclude certain prefix from whole routing. Voipswitch will reject all messages addressed to numbers matching that prefix
  • Route disabled - the option temporary disables the route (provider), the entry will be skipped by the routing function
• SMS Provider - the provider chosen for the route, it has to be picked up from the drop down list containing all entries from the Routing/SMS/Providers table.