Everything you need to know to start with the SMS service

From Complete Cyclos documentation wiki
Jump to: navigation, search

Everything you need to know to start with the SMS service

Basic concepts

The system is composed by two modules, Driver and Controller. The Driver work as a proxy between the communication channel and the Controller. The Controller do the routing and command parsing. Several Drivers can be plugged to the same Controller module to handle diferent communication channels. Those two modules are really close related.

The driver support different communication channels. Every channel is considered to work with asynchronous messages. You can work with SMS by several means, GSM modem, a service provider or a direct connection with the TELCO talking SMPP. The actual version of driver support GSM modem through SMSLib and services providers through HTTP or HTTPS connection.

The controller take care of messages routing between Cyclos and Drivers. The routing from Driver to Cyclos is done based on a mapping from driver name to cyclos name. The inverse routing from Cyclos to Driver could be a little more complex routing messages based on the Cyclos name plus a member field (generally the TELCO).

In a general setup, you can be working with different service providers. These providers don't need to be working together, they may be offering messaging service for different countries or different telcos.

We can think of different Cyclos instalations servicing different countries and working independently. Each country probably would work with a different short number, although, they could use the same short number. In this scenario we should have one driver and Cyclos for each country and one controller. The driver will work as a proxy between the Controller and the service provider, telco or GSM modem depending on the setup.

Conceptually we can think there is no controller and the driver is the channel. Here the channel (service provider, GSM modem, etc) is connected directly to the Cyclos instances and Cyclos knows exactly where to send messages. This conceptual view is carried out by the Controller module.

Controller specific


The part of the system that takes an action is based on the idea of commands. A command is an entity able to carry out some task at the time a message arrives. It can take an action against a Cyclos instance, although it can answer the message by itself. There are different types of commands you can setup for every Cyclos instance. Each command is developed for a specific use case.

The system will choose a command to be executed based on the message text. This text will be matched by means of a regular expression. The first command that matches the regular expression is the one that will be executed. Command's parameters are defined in terms of regular expression groups, the first parameter is asociated with the group 2 and so on.


The routing is done in the Controller module. To be carried out there are two mappings, one from Cyclos to Driver and one from Driver to Cyclos. The Cyclos to Driver mapping is done based on two custom fields defined for every member. One of those custom fields defines what the TELCO is. The other custom field define the member's cellphone id. The mapping from Driver to Cyclos is easier, it is based only on the incoming number and driver id.

You can forget about the Controller and think conceptually about the connections between Drivers and Cyclos just like shown in the following image.

Conceptual view of the Controller - Cyclos linl

By adding the Controller to the picture you can see the role of the Controller is to make those links look like in the image above.

Conceptual view of the Controller - Cyclos linl

Driver specific

The main responsability for the Driver is to work as a proxy to isolate the Controller from the compexities of different communication channels. To acomplish this task the Driver is built with the idea of an Engine. The engine is responsible for the communication with the channel and there is one Engine for every supported channel.

There are several Engines. The SMSDriverEngine is responsible for communication using a GSM modem. The HttpGatewayEngine is responsible for communication through a Gateway. You can add more Engines as you need them.

SMS Connectivity

Connectivity to gateway

Cyclos shuttle service for transactions via SMS can work through an SMS Gateway poveedor. Provider Gateway is designed to a more stable base and facilitate negotiations with each locale telcos

Abbreviations and Concepts

TELCO Company cell phone and SMS service
MO Cells that originated the message (Originated Message)
MT Cellular recipient of a message (Mobile Terminated)
ISP It is a service provider that allows the sending and receiving SMS messages with a number of cellular service operators (TELCO)
GSM MODEM An electronic device that allows the sending and receiving messages (and / or data) in a cellular network. In current cellular networks, this device requires an ID chip, known as SIMM to operate.

Gateway connectivity Connection for sending and receiving SMSs
The Gateway must be connected to applicative Cyclos (specifically the Driver SMS) to send you SMS messages received from mobile phones. Similarly, the DriverSMS of Cyclos must connect to the gateway to send SMS messages and transaction reporting. The SMS service needs invariably half Cyclos (Gateway or Modem) to release and receipt of messages. Working with a Gateway is probably the greatest benefit option can provide.

Network Protocols
The supported connection between the Driver and the service provider is HTTP or HTTPS. You can also negotiate a VPN connection with your service provider. However connecting through a VPN or not, we always recommend to use the HTTPS connection to improve security.

Communication protocol
It is the way the Gateway and the Driver module will interact. It is accustom to use REST or SOAP as communication technologies, altough we are not limited to those technologies. An agreement should be made between the Gateway and Driver technical staff about the communication protocol so one or both of them could start developing and testing the integration.

TELCO works with
It is important that the chosen provider Gateway operates with all the TELCOS you want integrate with. This is important for two reasons:

  • The cost of messages between two TELCOS is usually more expensive than one message within the same TELCO
  • We require a short number to be unique among all the telcos to ensure that all phones (regardless of the TELCO to which they belong) send messages to the same number.

Short Number
There is typically only one short number to receive SMS messages. This short number must be requested in each TELCO you want to operate. It is usually easier for Gateways to negotiate short numbers among different TELCOS, in that case the only you need to do is give all information the Gateway ask for.

Cost of service
In general there are two types of contracts

  • You pay a fixed monthly amount to the Gateway. In some cases this include a maximum number of SMS.
  • You pay for SMS traffic.

Message Costs
Except the case of MT recovery message (see Message billing MT), all other messages sent by Cyclos would generate a cost to the organization that operates it. That cost is fixed by the TELCO through which the message is sent. Telcos generally tend to work by selling packets of messages, which are valid at the time (similar to a prepaid card for sending SMS messages). For this reason, the cost of sending an SMS message can depend on TELCO whereby the trafficked. In some cases gateway providers charge the organization with a cost per message traffic (received as sent, in whatever form). This cost is added to the monthly fixed cost for the service and will depend on the volume of message sent and / or received from each of the TELCO with which they work. NOTE: when the personal interview with a Gateway provider, check what are the fixed costs for the service and whether there are variable costs depending on the traffic of messages (or otherwise).

MT message recovery
Often organizations want to avoid variable costs. For these cases you can use the MT message. This type of message is charged to the recipient thereof. Depending on the laws of each region (country), may require additional clauses in contracts with users who access this service or a kind of instantaneous activation and deactivation of the same (eg via SMS). In general the cost charged for the message to the recipient exceeds the cost of a normal SMS and must be specified and informed service user. The price for the message must be negotiated with the TELCO when requesting the services of short number (for details, see the section on short number). In some cases the Gateway operator can add a fee to his favor at the cost of MT (payable by the recipient of the message). NOTE: At the time of the interview with the gateway is important to record the plans that they suggest (and whether they can work on your order against the TELCO) service for the show, and make an outline of costs for each message.

Transfer service ID (Caller ID)
Every SMS you receive comes with the service ID of the sender (The caller ID is the cellphone number). This information is essential to identify what member sent the message and that way validate the transactions. NOTE: Sometimes (especially when the message is transferred from a TELCO to another, or when the message travels across international borders), that information may not get properly. At the time of the interview with the Gateway's staff is important to note that ID is required for us to work properly.

Safety Requirements
As Cyclos operates on economic transactions special attention must be paid to data security. SMS messages should include personal data as transaction PIN, username, etc. In many countries, personal data are regulated by law. You must take into account the legislation of the region to assess the requirements of confidentiality of the information contained in the messages. For this reason the data and the means of transfer must be consistent in its protection. See also the connection point for sending and receiving data

Telecom connectivity
Gateway operator must connect each of the TELCO in which it does (to send and receive messages). Special attention should be paid to the security of data transfer. NOTE: at the time of the interview with the operator of Gateway is important to emphasize this fact and point out that security in data transfer becomes a key point. Try to get as much information as possible about the background of the Gateway operator in terms of security in their methods of operation.

Logs, and confidentiality clauses
It is important to include confidentiality clauses regarding the data that is included in messages that are trafficked, and the logs that are kept from them. NOTE: To avoid surprises, at the time of the interview with the staff of Gateway providers do note that the request will include confidentiality clauses referring to the data traffic in the messages.