SMS notifications

The sendsms service provides the ability to send SMS to mobile devices. This service may be used by other services that need to reach users via SMS. The SMS will be created by already defined templates. These templates will include key words to be replaced by variable values. In addition there is the possibility to create different SMS texts based on the language selected. All the features provided by the sms service are supported by the underlying external service Beepsend. This external service has an API with which we can send SMS from the platform. To properly get this service working, it is necessary to create a profile on the provider platform. Check specific configurations on the corresponding backend configuration section.

Configuring the service

The service is configured via the wac.ini file as usual. It contains a top-level entry named [sendsms] that holds the service’s details.

[sendsms]
backend[] = sendsms
; backend[] = linkmobility

Optional paramters

  • templatePath: This key will define the path where to look for templates (defaults to <rootdirectory>/config/smstemplates).

It can be used as an absolute path or as a relative path. E.g.

templatePath = ./otherfolder

In order to find the templates in <rootproject>/config/otherfolder.

Available backends

  • sendsms send SMS using Beepsend API. The backend will connect using a connection token with the API and will send one or several messages. When a message has more than 70 characters, Beepsend will create two related messages.

[backend.sendsms]
module = sippo-sms-bs
urlService = https://api.beepsend.com
token = xxxxxxxxxxxxxxxxxxxxxxxxxx
from = Quobis

Backend parameters:

There are three mandatory options to be provided: urlSevice, token and from.

urlService:

The BeepSend API URL

token:

Connection Token for authentication.

from:

The sender id. It must be a string with one of the following formats:

  • Alphanumeric. Maximum allowed characters are 11.

  • MSISDN numbers or short numbers / codes. Between 9 and 17 chars.

  • National format. Maximum length is 7 chars.

encoding:

Allows you to specify the message encoding . Available options are UTF-8, ISO-8859-15 or Unicode. Defaults to UTF-8.

Link mobility send SMS using the LinkMobility provider. To use it, enable it in the wac.ini file and set up the required parameters as follows:

[backend.linkmobility]
module = sippo-sms-linkmobility
login = username
password = <your_md5password>
from = QUOBIS

Creating new templates

Templates use the handlebars syntax. It’s an easy and intuitive replacement syntax. Just wrap your items to be replaced with {{ }} and you’re ready to go. Please take a look at provided template and website to learn more about it. To have a template ready to use, please drop it in a new folder inside templatePath. For instance, if you want to add a new template for sending SMS for meetings, you can create a new folder called myMeetingsSMS inside templatePath and copy there your template files.

Template naming rules

Template must adhere to a strict but simple naming rules. As the sms service sends only plaintext, the plaintext template is mandatory. The file must be named text.hbs. For example, this might be the real contents of templatePath:

templatePath/
`- myMeetingsSMS/
   `- text.hbs

Localization of templates

There is also support for localization of templates. From the administrator point of view is as easy as creating a subdirectory of the template directory named after the locale to be used. That is, for our example myMeetingsSMS template we can provide a Spanish translation by creating a folder es inside it with the corresponding localized templates:

templatePath/
`- myMeetingsSMS/
   `- text.hbs
   `- es/
      `- text.hbs

If no translation is requested, the myMeetingsSMS contents will be used.

Activity diagram

@startuml

participant "SendSMS\nservice" as service
participant "SendSMS\nbackend" as backend
participant "Backend platform\nAPI" as backAPI #lightblue
actor "User phone" as user

activate service
service -> backend: send(language, to, meetingURL)
activate backend
backend -> backAPI: send(to, message)
activate backAPI
backAPI --> backend: response API
deactivate backAPI
backend --> service: return response
deactivate backend
deactivate service
rnote over backAPI: async delay
backAPI -> user: SMS delivery
@enduml