Aller directement à la fin des métadonnées
Aller au début des métadonnées

This document serves to provide a description on how to Configure/Add a SMS Provider for the CiviSMS feature of CiviCRM.


Configure Clickatell or Twilio

Configure Clickatell

Create a Clickatell account

First of all it is necessary to have an account of the SMS Provider that we are going to use, Clickatell, in our case.

Go to the Clickatell website ( and sign up for an SMS Gateway, Clickatell Central account. Signing up to Clickatell Central  is free, as a bonus you get 10 free message  credits.

Note: the Developer's Central API is "global" which does not include the US.  So, if you want to send to recipients in the US, you need the Americas 2 Way SMS API (formerly known as "Small Business API") which is a 2-way number.  (Sending SMS with the gateway account seems to work on CiviCRM's side, but results in a "routing error" on the Clickatell side).  You may have to pay the monthly fee for at least one month to get everything set up on this kind of account.

Create a Clickatell HTTP API product

In Clickatell Central, use the Manage My Products page to add a HTTP connection. This will generate an API ID that, together with your username and password, you need to add it to the SMS Provider settings of CiviCRM.

Enable SMS Status Notification (MT Callback)

Final or intermediary statuses are passed back by the API depending on the callback value set in the original post / sms

The sms code by default sets the callback to the value 3 which Returns both intermediate and final statuses of a message if callback url is set.

A callback url could be setup in your Clickatell central account to receive 'SMS Status notifications'.

The example of a url is:

Use HTTP GET / POST options for callback URL.

Handling replies

This is only valid if you have signed up and paid for two-way messaging service.

  1. In the Clickatell menu, click on "Americas 2 Way SMS" or "Small Business API" in the top navigation menu.
  2. On the following screen, you should see your assigned 2-way number.  Click the "manage" link next to it.
  3. Under "Primary Callback", set a callback method (Reply Path), either HTTP POST (preferred) or HTTP GET (also works).
  4. For the "Target Address", supply the same callback URL you used above.  You don't need a username or password.
  5. Click "Save Changes".

All Inbound SMS are created as activities in CiviCRM against the TO and FROM contacts.

Short codes

todo: The code currently doesn't support or does anything on its own for short codes. Not sure about renting process.

Download & Install extension

Download and install required extension from the extensions directory.  Administer menu > System Settings > Manage Extensions, then "Add New" and find the Clickatell extension.

NOTE: Clickatell requires a country code on your mobile phone numbers.  For instance, US-based numbers can't be "212-555-1212", but "1-212-555-1212" works.  There is a patched version of the Clickatell extension that removes this requirement, but assumes you are only contacting have US and/or UK numbers here:

Configure SMS Provider Settings in CiviCRM

To reach the SMS provider settings page, navigate through the menus as follows:

  1. Administer » System Settings » SMS Providers
  2. Click on "Add New Provider" button.
  3. In the Manage SMS Provider Page, the provider Clickatell is selected by default(as Clickatell is the only sms provider configured for CiviCRM presently).
  4. Type some name for your sms provider in the Title textbox.
  5. Type in the Username and Password of your Clickatell account. Be aware that your Clickatell API password may differ from your Clickatell account password.
  6. Select "http" for the API Type. The API Url defaults to "" for Clickatell.
  7. Under API Parameters, you can provide the parameters separated by new line that is to be passed in the post data.

Like:  api_id=1234567  (For API ID, Refer step #2 )

8. If you have a two way account (including Small Business API/America 2 Way SMS API) you need two additional API Parameters:

from=[11 digit number that clicktell provides]


So an example configuration on the CiviCRM side under SMS Provider API parameters might be (with 2 way messaging):


Now, the SMS Provider is configured and it can be used for sending SMS's to contacts.

Test account

For test account, there is no need to create a Clickatell account.

Refer the following steps to create a Test Account:

  1. Follow the same steps as above i.e. steps 3(a), 3(b), 3(c) and 3(d).
  2. You can provide any values for the Username and Password. eg username = "testuser", password = "testpassword".
  3. Select the API Type as "http" and leave the API Url as it is(It defaults to "" for Clickatell).
  4. Under API Parameters, provide the parameters as is_test = 1 and api_id = 1234567 or some random number, the parameters being separated by a new line.

Now, the test account of the SMS Provider is configured and can be used for sending SMS.

Configure Twilio

Create a Twilio Account

Go to the Twilio website ( and sign up for an account. You can create a trial account and test, but you will need to upgrade your account in order to send SMS messages properly.

Download & Install extension

In the CiviCRM Administer Menu, click on System Settings and then Manage Extensions. Click on the Add New tab and install the twilio extension.

Alternatively, you can download and install required extension from github -

For setting up twilio the extension is : org.civicrm.sms.twilio

Configure SMS Provider Settings in CiviCRM

To reach the SMS provider settings page, navigate through the menus as follows:

  1. Administer » System Settings » SMS Providers
  2. Click on "Add New Provider" button.
  3. In the Manage SMS Provider Page, the providers that are enabled are available. Choose Twilio.
  4. Type some name for your sms provider in the Title textbox.
  5. The Username is the AccountSid.
  6. The Password is your AUTH token.
  7. Select "http" for the API Type. The API Url is for Twilio/
  8. Under API Parameters, you need to put in the phone number Twilio provides for your account, like this:
    From=+12345678901 (enter +1 in front of your number, no spaces, dashes or brackets in the number). Swap 1 with the country-code of your Twilio phone number, ie 1 is the country code for USA and Canada.

Configure for inbound SMS

If you want the incoming SMS to be recorded in CiviCRM, follow the steps:

  1. In Twilio account settings, go to Numbers and click on the number you want CiviCRM to "listen to". That will open configuration settings for that phone number. Under Messaging, change Request URL to http://yoursiteurl/civicrm/sms/callback?provider=org.civicrm.sms.twilio with HTTP POST
  2. In CiviCRM, under SMS Providers, edit your Twilio settings and add to API Parameters: mo=1 so that in API Parameters there is:
  • Aucun
  1. Jan 18, 2017

    On the clickatell page Add Connection HTTP API ( there is an option as follows


    I am wondering if CiviCRM supports this?

  2. Sep 29, 2014

    Hi thanks for this useful feature
    Could it be possible to add Fronline SMS to the possible providers configured by default ?

    I think it would be more relevant for CiviCRM than other capitalistic companies.

  3. Oct 13, 2014

    Carmen Neely dit :

    PLEASE NOTE: The following TWILIO API Parameter format for the phone number that worked for me is "From=+12345678901". I am using CiviCRM 4.4 and WordPress 3.9 and the API Parameter format as listed above "FROM=12345678901" did not work for me.

  4. Dec 15, 2014

    When sending using Twilio, I get the following error:

    Perhaps related to Carmen Neely's comment above. Twilio seems to be case-sensitive about the API, so 'FROM' doesn't work, but 'From' does. I'm wondering if the same thing is happening with the body. Is it being sent as 'BODY' or 'body', rather than 'Body'? I had a quick look through the code and nothing jumped out at me. I'll keep looking, but in the meantime I'm hoping someone else has come across this too.

  5. Feb 23, 2015

    Melvin dit :

    I tried with Twilio and Clickatell, and I get the same error: " Selected contact(s) do not have a valid Phone, or communication preferences specify DO NOT SMS, or they are deceased" I am in the USA, using CiviCRM 4.5 on Joomla 3.3.  I need help on this.  Please

  6. Feb 23, 2015

    To send a message to a contact in CiviCRM, make sure that this contact has a phone of type "Mobile" and that the phone number starts with 1 (and then area code and a number), otherwise you will get an error as Melvin posted above.

  7. Feb 24, 2015

    Melvin dit :

    I have tried to format my phones number in different ways, and anything is working. I have tried: 17012199732, or 1-701-219-9732, 1 701-219-9732, +1701-219-9732. Is there any other way that I should be formatting my phone numbers?

    Note: I am sure my contacts are not marked as Do Not SMS or deceased. 

    Is it possible that a setting in my joomla, php, or anywhere else is causing the issue?

    1. Apr 21, 2015

      Melvin, if you still haven't solved your issue, you can try just the php from Twilio with your SID and Auth Code; the format that seems to work is country code 1 followed by area code + number, no hyphens, as Kasia said.

      1. Apr 22, 2015

        Melvin dit :

        I moved to wordpress, and it worked


  8. Apr 12, 2015

    Using Twilio and would like to enable callback for incoming messages and I am unsure on the URL: 


    I don't have a mapping for a /civicrm/ directory. If you would use the unmapped url construct: 


    Also tried:

    The error message from twilio log is: 

    12200 Schema validation warning

    Cvc-elt.1: Cannot find the declaration of element 'html'.

    Any idea what the correct callback URL would be? 

  9. Oct 29, 2015

    Hi, Twilio user here

    I've got it installed and setup and working - also with the newest version of the Twilio API where you can use alpanumeric sender ID instead of a Twilio phonenumber.

    It didn't go smooth though. My first problem was that I couldn't send Bulk SMS, but only single SMS'es through action button at the contact record. The problem is what I believe to be a bug in the CiviCRM Mail code, I've filed an issue and suggested a patch here:

    I'm using the suggested code and it works for me, so I can send Bulk SMS.

    The Twilio extension for CiviCRM uses quite outdated API code from Twilio, and thus cannot out of the box use alphanumeric sender ID. To fix this I downloaded the most recent API code, and simply deleted the Services folder in the Civi extension and added the Services folder from the dowloaded API. Be aware that I've only tested sending SMS'es with the new code, as I don't need to recieve SMS'es, so I cannot guarantee that anything else will work, and if you do this it's at your own risk.

    Very well, then to send using Alphanumeric Sender ID you need to add an additional API parameter for the provider at civicrm/admin/sms/provider AND add some code to org_civicrm_sms_twilio.php in the send function.The parameter I added was just one I made up, so I could do a check in the send function to see if we are sending with sender ID. So if your API-parameters looked like this before:


    you can now change it to this:


    where MySenderID is whatever alpanumeric string you want with at most 11 characters (well, only [A-Za-z_ -]+)

    Now the send function in org_civicrm_sms_twilio.php looks something like this:

    $from = '';
    if (array_key_exists('From', $this->_providerInfo['api_params'])) {
      $from = $this->_providerInfo['api_params']['From'];
    try {
      $twilioMessage = $this->_twilioClient->account->sms_messages->create(
    } catch (Exception $e) {

    Change  that to

     $from = '';
    if (array_key_exists('From', $this->_providerInfo['api_params'])) {
    $from = $this->_providerInfo['api_params']['From'];
    $useSenderID = FALSE;
    if (array_key_exists('UseSenderID', $this->_providerInfo['api_params'])) {
    $useSenderID = ($this->_providerInfo['api_params']['UseSenderID'] === 'True') ? TRUE : FALSE;
    try {
    if ($useSenderID) {
    $twilioMessage = $this->_twilioClient->account->messages->sendMessage(
    } else {
    $twilioMessage = $this->_twilioClient->account->sms_messages->create(
    } catch (Exception $e) {


    And thats it - you should now be able to send bulk SMS and use alphanumeric sender id with Twilio.

    NB: Like others I had to put a + character in front of my twilio number to get it working - the doc above didn't have that, so I've edited the doc to include the + character and mention that 1 is the country code for USA and Canada. Example: I'm from Denmark, my Twilio number begins with the Danish country-code 45, so instead of +1 my Twilio phone number begins with +45.
    A related problem: You'll probably run into the problem that most of your phone numbers in Civi doesn't include your countrycode, and Twilio will not sent to phonenumbers without the countrycode. To fix this I've added the following code to the send function in  org_civicrm_sms_twilio.php:

    function send($recipients, $header, $message, $jobID = NULL, $userID = NULL) {
    // if the phone number doesn't begin with + or 00 we add the country code (00 are sometimes used as a substitute for the + character)
    if (!(substr($header['To'], 0, 1) === '+' || substr($header['To'], 0, 2) === '00')) {
    $header['To'] = '+45'.$header['To'];


  10. Apr 28, 2016

    G H dit :

    When using Clickatell for SMS to get replies back in, I had to use HTTP Get as HTTP Post returned HTTP 503 errors on the Clickatell report page.  Others?  Did I do something wrong?