1.8.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, PBX UC and wholesale client types. The retail/PBX UC 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
• OTP Callback
• Text to speech

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

The URL should be as follows:

https://yourdomain:3000/sms/send-offnet?login=!LOGIN!&pass=!PASS!&text=!TEXT!&from=!FROM!&to=!TO!&id_cc=!ID_CC! 

 Voipswitch 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 VSM4 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 menu, click on a particular tariff and then press the SMS Rates tab,

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 SMS Routing/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, SIP, Text-to-speech callback or OTP callback. 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
• User name – 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://smpp4.routesms.com:8080/eurosms/sendsms?

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
• Use 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.

Additionally Encoding can be set for SMPP messages. Below is the list of supporting encoding:

• DEFAULT
• ASCII / GSM_TR / GSM_ES / GSM_PT IA5
• LATING1 / ISO_8859_1
• BINARY
• JIS / X_0208_1990
• CYRILLIC / ISO_8859_5
• HEBREW / ISO_8859_8
• UCS2
• PICTOGRAM
• ISO_2022_JP
• EXTENDED_KANJI_JIS / X_0212_1990
• KS_C_5601

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") 

It applies only for windows version of Voipswitch application!!!!

Text-to-speech callback 

The text to speech allows us to hear the received sms by calling us and playing the sms content.

 OTP callback

This provider can be used to send an OTP code to the callback function, initiating the call. The new user will receive the call and be able to complete their account creation by entering the OTP code received during the phone call using the Say OTP code IVR scenario.

To set this up we need to add OTP callback provider with a predefined Callback destination number  for example 99999993.

Once done we need to go under Calls routing/Routing Plan and add a prefix 99999993, set Route type as VoipBox with selected Say OTP code scenario.

Under destination number we need to cut off the predefined number "99999993->" so the scenario would play only OTP code.

SMS routing plan

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

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

The switch 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 VoipSwitch 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 VoipSwitch 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 SMS Routing/Providers table.