Skip to content

Set-up

In this chapter, the steps required to set up an SMS gateway will be explored. Once configured, you will be able to send both single and mass text messages to individual contacts which have a mobile phone number defined, ie. Phone Type must be "Mobile".

Note: Contacts which do not have a mobile phone number defined will not receive a SMS text message.

Permissions: Users require the CiviCRM: send SMS permission to see SMS menu items and send SMS.

Configuring a Clickatell SMS Gateway

Registering for a Clickatell account

The Clickatell service is an online SMS gateway designed for the sending of text messages via the Internet. They offer several products, but here we are only interested in the "Developer's Central" SMS gateway, as it offers more advanced tools needed to link it to CiviCRM (this is achieved through APIs; see the CiviCRM developer guide for more information). Registering for a Clickatell account is free, and they supply 10 complimentary credits to try the service. To sign up, visit:

http://www.clickatell.com/register/

Once you have registered for a Developer's Central account, please sign-in and follow the steps below (when logging in you must select Central API as the product and enter your Client ID):

  1. In the Central Home dashboard, click Create a new Connection under Connection Status (New language is Get another API. Page looks also changed.)

Clickatell settings screen

  1. Select HTTP/S as the connection type (New language: HTTP API)

  2. Four optional settings will appear, including:

    • Description: change the name of the connection (e.g. "CiviCRM HTTP")
    • Replace leading zero: enable this option if mobile phone numbers against your contacts begin with "0". For delivery to be successful, all numbers must begin with the country code if this is not enabled. (This option no longer exists.)
    • Enable IP Address Restriction: if you know the IP address of your CiviCRM server, you can enter it here to ensure that text messages cannot be sent using your account elsewhere (your username and password would be needed to do this) (New language: "Protect your account from fraud by restricting IP addresses")
    • Enable your app to receive message delivery notifications (New option?) Enter the correct URL for your site. Example: Drupal: http://www.example.com/civicrm/sms/callback?provider=org.civicrm.sms.clickatell WordPress: https://www.example.org/?page=CiviCRM&q=civicrm%2Fsms%2Fcallback&provider=org.civicrm.sms.clickatell

  3. Click Submit and Get API ID to generate an API ID, and on the next page, make a note of it.

Completing the SMS Provider settings in CiviCRM

You now have all of the information needed to configure SMS in CiviCRM. After installing the Clickatell extension in CiviCRM, go to: Administer > System Settings > SMS Providers. Click Add New Provider.

image

Complete the following settings:

  • Name: select Clickatell
  • Title: give the SMS provider a title user's will see (e.g. "Clickatell SMS")
  • Username: enter your Clickatell username
  • Password: and your Clickatell password
  • API type: select http
  • API URL: type the URL as follows: https://api.clickatell.com
  • API Parameters: this is where you should provide your API ID. The format required is: api_id=8473658
  • Is this provider active?: tick to enable the SMS gateway
  • Is this a default provider?: check this option to make it the default, where multiple SMS providers are available

CiviCRM will now be configured to send text messages to your contacts.

Testing the SMS gateway

You can begin testing the gateway using the methods laid out in the chapter Everyday tasks. However, please note that if you are using the 10 complimentary SMS credits which came with the account, until you have purchased credits Clickatell will replace the content with thank you text like the message below:

Thanks for testing Clickatell's gateway coverage. You will be able to change the content of your message after your initial purchase of message credits.

After upgrading your Clickatell account to a paid account

Once you have upgraded your Clickatell account, you will need to change a few parameters to get things working again. In CiviCRM, go to: Administer > System Settings > SMS Providers and click Edit on your Clickatell provider. In the API Parameters box, under the api_id line, add a from= and a mo=1 parameter. The from= number is the mobile phone number associated with the api_id in your Clickatell account.

Your API parameters should now look like: 

api_id=8473658
from=15551234567
mo=1

Back in your Clickatell Developer's Central page, click on the America's 2 Way SMS tab, then click Manage next to the mobile phone number you are working with. For the Primary Callback: Reply Path, choose HTTP Get from the dropdown. In the target address, enter the same address as used before: Drupal: http://www.example.com/civicrm/sms/callback?provider=org.civicrm.sms.clickatell WordPress: https://www.example.org/?page=CiviCRM&q=civicrm%2Fsms%2Fcallback&provider=org.civicrm.sms.clickatell

Configuring a Twilio SMS Gateway

Registering for a Twilio account

Twilio offer a wide range of communications and telephony services in most countries. CiviSMS uses the Programmable SMS feature. You can register a free trial account, which will allow you to test the service.

To sign up, visit:

https://www.twilio.com/try-twilio

Once you have registered for an account, you will be asked to verify your account phone number via SMS or call. You will then be taken to the Console.

Getting a mobile phone number

Your trial account entitles you to a free rented Twilio mobile phone number, which you can use to send SMS. However, free accounts must verify a mobile phone number before it can receive SMS. For the purposes of this guide, we will send a message to the same mobile phone number you verified in the registration step.

  1. From the Console homepage, click the Programmable SMS product.

  2. Click the red Get Started button.

  3. Click the Get a number button, near the top of the page. A mobile phone number will be suggested to you. If the country of the number is not accurate, use Search for a different number. Otherwise, click Choose this number, and Done, after noting down the number.

You now have a rented mobile phone number that can send and receive SMS messages.

Setting up your new mobile phone number in Twilio

  1. Click the All Products & Services icon, in the far left navigation bar (or click on Develop > Super Network > Phone Numbers).

  2. Choose Phone Numbers.

  3. Click your new number from the list to set it up.

  4. Under the Messaging section, change the "A message comes in webhook" to the following, replacing example.com with your CiviCRM installation.

For Drupal, use https://example.com/civicrm/sms/callback?provider=org.civicrm.sms.twilio

For WordPress, use https://example.com/civicrm?civiwp=CiviCRM&q=civicrm%2Fsms%2Fcallback&provider=org.civicrm.sms.twilio

This will send any replies that your messages receive back to CiviCRM.

Messaging

  1. Click Save.

Getting your Twilio provider settings

  1. In the Twilio Console, go back to the Console homepage.

  2. Copy down your Account SID and Auth Token (you will need to click the token to reveal it).

You now have all of the information needed to configure SMS in CiviCRM.

Setting up your new SMS Provider in CiviCRM

Now that you have a Twilio account with a mobile phone number, it needs to be set up in CiviCRM.

  1. After installing the Twilio extension in CiviCRM, go to: Administer > System Settings > SMS Providers. Click Add New Provider.

image

  1. Set up the provider as follows:

    • Name: select Twilio
    • Title: give the SMS provider a title user's will see (e.g. "Twilio SMS")
    • Username: enter your Account SID from the previous step
    • Password: enter your Auth Token from the previous step
    • API type: leave as http
    • API URL: leave as https://api.twilio.com/
    • API Parameters: enter From= followed by your Twilio mobile phone number from the previous step, in international format with no spaces. On a second line, enter mo=1.

    Note

    Twilio will only allow you to send around 200 messages per day from each long number. If you want to send more messages per day and you cannot afford a short code, you can get additional long numbers from Twilio. Include those additional numbers by listing them, separated by a | (the "pipe" character). For example: From=12345051212|19875052323|15675052345. When you include multiple long numbers, one number is chosen at random each time an SMS message is sent.

  2. Click Save to create your provider.

Testing CiviSMS

You can now use CiviSMS to send an SMS message to any mobile phone number you have access too.

See Everyday Tasks for some ways you can send messages.

If you reply to an SMS message, it will be created as an activity on your CiviCRM record.

Upgrading Twilio

To properly use Twilio as an SMS gateway, you will need a paid account.

You can upgrade your account to a full account by clicking Upgrade in the top right corner from the Twilio console.

Once you have upgraded, your rented mobile phone number will be available for full use, and charged against your Twilio credit.

You will now be able to send SMS to any mobile phone number.