Extensions‎ > ‎

Clickatell

Getting started

In order to use the Clickatell gateway you need a Clickatell account and at least one registered connection (API sub-product instance) between your application and the Clickatell gateway. Each connection method is known as a sub-product. You can follow these steps to get started:

Step 1 - Sign up for an account with Clickatell


If you already have a Clickatell Central account, proceed to Step 2 for instructions on how to edit an API connection on your account.

If you do not already have a Clickatell Central account, you need to register for one. You can do so at https://www.clickatell.com/register/?productid=1 by signing up for the Developers' Central product. On sign up for you will be given a username, password and a client ID. Please note that the client ID is not the same thing as the API ID, which we will setup later. If you registered for the trial, you will have received 10 free credits with which to test the service. Messages sent with these credits contain a canned (pre-populated) message. You can test the API using these credits or purchase credits to start sending your own customised messages.

Step 2 - Setup Clickatell

Action Form integrates with Clickatell using SOAP API. This needs to be setup in Clickatell Developers' Central. Login at https://www.clickatell.com/login/ and add the SOAP API to your account from APIs > Set up a new API > Add SOAP API. Complete all the required fields to configure your API. After successfully adding a connection, a confirmation message will be displayed with a unique API ID and information on how to get started. It displays the API connection parameters and authentication details. These are required when connecting to the Clickatell gateway from Action Form to send a message.
You will need this API's ID for Action Form. (not the SOAP API name). You can double check this API ID in the main menu: APIs > Manage APIs.

Step 3 - Setup Action Form

Once you have the Clickatell username, password and the SOAP API ID, you can proceed to setup Action Form. The Clickatell integration is provided as an add-on that can be purchased from DNN Store. So you will need to already have Action Form on the server before installing the Clickatell add-on. You can install both packages from Host > Extensions.

In this guide we will create a simple form to send an SMS message to a single phone number supplied in a text box. Start by adding a new Action Form module to the desired page. At the initial configuration step, for demo purposes, we will choose a Blank Form. It creates an empty form so you build everything from scratch. For our example we will need a text box to collect the phone number and a textarea for the message. Add these using the Add Field button in Action Form - Manage Screen. 

Next, add a button which will push the message to the Clickatell API. The action can be found under Add Action > Communications > Send SMS via Clickatell gateway. Here, you will use your username, password from Step 1 and the SOAP API ID from step 2 from above. Finally, we will need to wire the phone number and the message fields to the respective settings under the Clickatell action. We do this by referencing the form fields using their token syntax. Assuming the fields are named Phone Number and Message, the tokens that go under the Clickatell settings are [PhoneNumber] and [Message]. If configured correctly, it should look like in the following screenshot:

Action Form Clickatell extension, configuring on click handler demo

Save settings, go back to the front end. The form should look similar to 

Action Form with Clickatell extension module on page

Input your phone number, the message and click the button to have Action Form push the message to Clickatell and ultimately to your phone.

Settings Reference

This integration requires a valid Clickatell account and an SOAP API endpoint. Fill this in the first 3 fields labelled API ID, username and password. Note that the API ID that is created by default when you open the Clickatell account is a REST API ID, which will not work with current integration. Follow instructions at step 2 above for setting up a SOAP API ID.

The Clickatell integration allows the following configuration options:
  • Message
    This can be a text message, or it can be a token that references the actual message. The token can be either a form field, in which case it will pull whatever value was submitted with form, or it can be a My Token. Note that an SMS is limited to 160 chars. If the message is larger, it will be split automatically by Clickatell, and may be merged back into a single message depending on the delivery network and the receiver phone.

  • Max. Length of the Message
    This parameter is optional and allows administrators to limit the size of the messages that can be sent (for example, content submitted by users or content derived from user tokens). If set, it must be an integer. If left empty, there is no limit imposed by the administrator. Be aware that there is a limit though imposed by Clickatell, which is  5355 characters (SMS gateway technical  limits). The extension will truncate the text to this Clickatell maximum, even if field is left empty.

  • Phone Number(s) to Send TO
    SMS messages need to be sent in the standard international format, with country code followed by number. No leading zero to the number and no special characters such as "+" or spaces must be used. For example, a number in the UK being 07901231234 should be changed to 447901231234. You can send to more that one number by placing one phone number per line. The phone numbers can be hardcoded or can come from tokens - either form tokens such as [PhoneNumber] or DNN/My Tokens such as [Profile:Cell].