SMS/Dialer Module

The SMS/Dialer module allows you to send notifications to your Revolution contacts as:

  • SMS text messages via Clickatell or Twilio.
  • Text-to-speech or stored audio calls via Twilio.

  • You must have an active Clickatell or Twilio account.

  • If you will be using any sort of Response Options Notification, you must set up your Twilio or Clickatell accounts as described in Setting up Twilio and Clickatell for use with Response Options.
  • Ensure that the required Firewall/Port usage requirements have been met.
  • Your Revolution license must include support for SMS and Mass Dialer. Contact Sales if you need to add the module to your Revolution.
  • SMS Information
    • Twilio sends multiple SMS messages if the title, body, and prompt exceed 140 characters.
    • Consult your Clickatell vendor documentation to determine whether they truncate the content or send multiple SMS messages.
  • Dialer Information
    • A Text-to-Speech (TTS) notification type converts notification content to audio for internal endpoints. Twilio Mass Dialer allows you to extend this to external phones. Revolution uses Microsoft's TTS engine internally, which is different from the Twilio TTS engine.
    • A notification begins playing as soon as the call is answered. However, Twilio can't detect if a call is answered by a person versus voicemail. If the call is answered by voicemail, the beginning of the message will not get recorded. How much thereafter is recorded depends on the length of the voicemail greeting.
    • Twilio makes phone calls one at a time, not in parallel. The fastest it can make calls is 1 per second. Therefore, if you have many endpoints and contacts assigned to a notification, it can take a little while for all the calls to complete.
  • Twilio Account – used for notifications sent to contacts via SMS or Mass Dialers.
  • Clickatell One API Account – used for SMS notifications using the Clickatell One API interface.
  • Clickatell Legacy Account – used for SMS notifications using a legacy API for backward capability. This is specific to Clickatell accounts created before November 2016.

Note: All recipients of these notifications must be Contacts within Revolution. See Contacts for the various ways people can be added.

Access all of these tasks:

  • Go to Configuration > SMS/Dialer

  • Allow audio files for mass dialers – Enable this to send a pre-recorded audio file, rather than a text-to-speech reading of your message.

    When a Stored Audio Notification goes to contacts via the Mass Dialer communication method, Twilio will play the stored audio file, rather than a text-to-speech conversion.

    Revolution will only play the audio file. It will not play any opening or closing tones from your notification. If your notification does not include a stored audio file, it will use TTS for the notification text.

  • Dialer Message Template – For Mass Dialer messages, Revolution uses the following template for the text-to-speech conversion.

    Hello, this is {Title} from {CallerID}. {Body}

    The Title, CallerID, and Body variables come from your notification setup. Your message must contain all three variables, but you can remove, rearrange, or replace the static text.

    For example, I have a Portland Weather Alert notification set up. I want my weather alerts sent to our management team members.

    How Title and Body variables are inherited

  1. Select New > New Twilio Account.

  2. For Name, enter a name to make this account easily recognizable.

  3. (Optional) For Preference Order, enter an integer, where a lower number indicates higher priority. You only need to use this setting if you configure more than one gateway, which is not typical.

  4. For Account ID and Auth ID, enter the credentials required for your Twilio account.

  5. (Only mandatory if WhatsApp Integration is enabled) For Messaging Service SID, enter the Messaging Service SID from your Twilio account.

  6. For From Number, enter the phone number, including the country code, provided by Twilio for your account.

    If your Account Type will include SMS, this field accepts a Messaging Service SID, which may include alpha-numeric characters.

    If you also enable WhatsApp Integration, this value must exactly match your WhatsApp Sender Number, as defined in your Twilio environment and assigned to your WhatsApp business account.

  7. For Account Type, select whether you want to use this account for SMS or Text-to-speech notifications.

    • SMS – This account will only be available for SMS messages.
    • Dialer – This account will only be available for Text-to-speech messages.
    • SMS and Dialer – This account will be available for either SMS or Text-to-speech messages.

  8. (Only available and mandatory if WhatsApp Integration is enabled) For WhatsApp Template SID, enter the SID of the Twilio content template that will be used to send WhatsApp messages.

  9. (Only available if WhatsApp Integration is enabled) For WhatsApp Template variables values, enter the variable values of the Twilio content template that will be used to send WhatsApp messages. See Integrating Twilio with WhatsApp.

  10. (Only available if Account Type includes SMS) Enable WhatsApp Integration, if your SMS messages may also be sent to WhatsApp accounts associated with your contacts. See Integrating Twilio with WhatsApp.
  11. (Only available if Account Type includes Dialer) For Text-to-Speech Language, select one of the available languages, where English (American) is the default.
  1. Select New > New Clickatell One API Account.
  2. For Name, enter a name to make this account easily recognizable.
  3. For API Key, enter the ID required for your Clickatell account.
  4. For From Number, enter the phone number, including the country code, provided by Clickatell for your account.
  5. (optional) For Preference Order, enter an integer, where a lower number indicates higher priority. You only need to use this setting if you configure more than one gateway, which is not typical.

Note: You only need to use this process if your Clickatell account was created before November 2016 and have not upgraded to use the new One API.

  1. Select New > New Clickatell Legacy Account.
  2. For Name, enter a name to make this account easily recognizable.
  3. For API ID, enter the credentials required for your Clickatell account.
  4. For User Name and Password, enter the credentials for your Clickatell account.
  5. For From Number, enter the phone number, including the country code, provided by Clickatell for your account.
  6. (optional) For Preference Order, enter an integer, where a lower number indicates higher priority. You only need to use this setting if you configure more than one gateway, which is not typical.

Through your Twilio setup you can also send notifications to contacts who enable WhatsApp in their contact preferences.

  • Requires a WhatsApp business account.

  • Requires you to integrate Twilio with WhatsApp (refer to your Twilio documentation). This topic assumes you are familiar with your WhatsApp Sender accounts and your WhatsApp Templates, the latter must be validated for use by WhatsApp.

Within Revolution, use these procedures for integrating with your Twilio account that supports WhatsApp.

  1. Configuring Twilio. Ensure that:

    • The From Number matches the WhatsApp Sender account number in your Twilio setup.

    • The Messaging Service SID matches the Messaging Service SID in your Twilio setup.

    • WhatsApp Integration is enabled.

    • There is a content template defined in Twilio, with WhatsApp capabilities.

    • WhatsApp Template SID matches the Twilio content template SID.

    • WhatsApp Template variables values match the Twilio content template variables, see details below:

    The values of the Twilio content template variables must be specified in the same order as in the Twilio content template. The values should be enclosed by double curly brackets: {{}}. Leave the field empty if the template has no variables.

    If the values of the Twilio content template variables in Revolution do not match the content template in Twilio, Twilio will display an error, but it will not return the information to Revolution. An example is when the content template in Twilio has variable(s), but the WhatsApp Template variables values field is left empty in Revolution.

    You can use text variables from the available list when filling in the Twilio content template variables values.

    It is suggested to fill in the Twilio content template variables field, by entering the Twilio content template body, then replacing the variable numbers with values. It is also recommended to keep the two fields in sync: Twilio content template variables field in Revolution and the content template body in Twilio. Following the whole Twilio content template body is not mandatory, as Revolution will discard the text outside the variable values i.e. outside the curly brackets, but it may help.

    Note: When sending the WhatsApp message via Twilio, Revolution will use the What'sApp Template SID, the variable values i.e. the text enclosed by double curly brackets, and the body of the WhatsApp Template from Twilio that matches the template SID. Revolution will not use the text around the variables i.e. outside the double curly brackets or the notification body when sending WhatsApp messages via Twilio.

    For example, if your Twilio content template body is:

    Hello, this is a message for {{1}}: {{2}}.

    you could enter the following in the WhatsApp Template variables values field using the Caller ID variable:

    Hello, this is a message for {{{CallerID}}}: {{Your school is closed for weather today}}.

  2. Configuring a Contact for WhatsApp Support. You must configure a contact's phone number to receive notifications to WhatsApp.

  3. Creating Notifications to be Sent to WhatsApp. WhatsApp requires notification text to be in a pre-defined template, therefore it suggested you create notification specific to your WhatsApp and Twilio configuration.

A Revolution admin or the contact can enable WhatsApp for individual phone numbers.

  • Admins within Revolution:

    1. Go to Users Contacts & Sites > Contacts.

    2. From the Contacts tab, filter the list and open the contact for editing.

    3. In External Phone Numbers, select Edit for the specific number.

    4. Enable WhatsApp Capable.

    5. Select Save and Close.

  • Contacts within the self-management portal:

    1. Log in to your self-management portal

    2. In Phone Numbers, select Edit for the specific number.

    3. Enable WhatsApp Capable.

    4. Select Save.

Your integration between Twilio and WhatsApp includes approved WhatsApp templates. The format of these templates must be matched exactly within Revolution. This includes all punctuation, spaces, and case-sensitivity.

Note: It is suggested that you create a new notification for use with this integration instead of altering an existing notification. This is due to the restrictions on the Notification Body field to match your WhatsApp template.

  1. Go to Notifications > Manage and select New Notification.

    The following instructions will only describe fields applicable to WhatsApp integration. See Notifications Basics for an overview of creating notifications.

  2. General and Select Triggers: Configure these sections as needed for your notification.

  3. Actions: Configure this section as needed for your notification.

  4. Endpoint & Contact Selection:

    • Contacts tab: Select the contacts that should receive this notification.
    • Choose Contact Methods: Enable SMS.

    The information will go to any contacts you selected that also enabled SMS messages or WhatsApp messages.

Create your notifications as you normally would, except for Mass Dialer notifications where you must select Text-to-speech as the Notification Type.

For both SMS and Mass Dialer, you must enter in Title and Body text in the Message Details section.

You can optionally create Actions to enable response options. See Setting up Twilio and Clickatell for use with Response Options. See Responding to Notifications for information on what the contact will see or hear regarding the response options.

When you have created Clickatell or Twilio accounts, the Endpoint & Contact Selection section of your Notification screen will allow you to select SMS or Mass Dialer as Contact Methods for the selected contacts.

Assign contacts as recipients for each notification you want sent as email and select the SMS or Mass Dialer options in Choose Contact Methods. At this point you will be able to choose from any of the gateways you create. See Choose Contact Methods.

Overview of Endoint and Contact Selection pane

Sent Notifications cannot track whether an individual contact received a notification as an SMS message to their mobile device. Sent notifications log as successful when the notification is received by the SMS module.

You can send notifications that use Response Options to SMS devices or through the mass dialer, but you must set up your application to allow for this. See Response Options Notification.

Set up your Twilio account as follows:

  1. From your Twilio main dashboard, select the Phone Numbers icon (#).

  2. Go to Manage Numbers > Active Numbers.

  3. Select the Number used for responses and go to the Configuration tab.

    Note: You must set this number up as a two-way number.

  4. Set up the following, depending on if you expect call or SMS responses:

    1. Under Voice & Fax, set A Call Comes In to:

      • Webhook

      • https://rev-response-api.syn-apps.com/call/twilio

      • HTTP POST

    2. Under Messaging, set A Message Comes In to:

      • Webhook

      • https://rev-response-api.syn-apps.com/sms/twilio

      • HTTP POST

Set up your Clickatell One API account as follows:

Note: Response Options are not supported with Clickatell Legacy accounts.

  1. From your main Clickatell account page, under Channels, select SMS.

  2. Select your current SMS setup.

  3. Under Two-Way settings, set the following:

    • HTTP Method: POST

    • Enter target address: https://rev-response-api.syn-apps.com/sms/clickatell

Once you delete an account used for SMS or Mass Dialer, and there are no other SMS or Mass Dialer accounts configured, these contact methods no longer display for contacts when assigning them to notifications.