SMS Notifications

DOMOTICZ CLICKATELL SMS API MINI HOW-TO

Setup

Setup Clickatell account

To use the Clickatell SMS API, you need to register for an account at https://www.clickatell.com/register/.

Select "Developers Central, International".

Once registered you will get assigned a "Client ID".

This is an extra id that distinguishes between one or more users, using the same account.
For instance, you can install Domoticz instances for a living and each client of yours can use your Clickatell account, with a separate login and Client ID.
You need this Client ID to log in to the Clickatell dashboard, but you don't need to set this up in Domoticz.

Setup a Clickatell API

Once registration is all done, and you loaded your account with some credits, it's time to create an API.

On the Clickatell page, select from the API's menu "Set up a new API".
There are different kinds of API's to choose from, but Domoticz utilizes the HTTP API.
You can name it anything you want.

API Configuration

- Default maximum message parts allowed
The SMS subsystem of Domoticz (currently) sets the "Maximum Allowed message parts" to 3, which will override the setting that you put there.
- Automatically convert mobile numbers into international format
If you want to be able to enter your mobile numbers on the Domoticz settings page in a local format (e.g. 061234567), then select your country here.
- Protect your account from fraud by restricting IP addresses
Optionally, you can enter the (external) IP address that your Domoticz instance connects from to Clickatell. This is an extra security measure.
- Enable your app to receive message delivery notifications
Currently delivery reports are not supported in Domoticz and this setting can be left "Off".

Now, in the "Manage API's " submenu, you can view the API ID of the HTTP API that you just created.
Take a reference of it, as you need to enter it in the Domoticz Notifications settings menu.

SenderID

Another thing that needs to be done is register a sender id. For this, on the Clickatell loginpages, go to "Manage Account" (on the right top) and then select "Manage Sender ID".
Click on "Add Sender ID" and fill in your mobile number.
You will receive an authorization code on this number that you have to fill in on the page so Clickatell knows this number belongs to you.
After having set this up successfully, the status will change to "Approved".
This indicates that you can use that number in the "From" setting of Domoticz.

Note that it is theoretically possible to register an alpha numeric sender id.
But this ID is mostly given out to Business Companies only, and is granted yes/no manually by Clickatell.

Configure Clickatell in Domoticz

In the web interface, go to Setup -> Settings -> Notifications and you see 5 fields that you need to enter in order to use the SMS API.

API Key: is the ID that was assigned to your (http) api
User ID: the same that use use to login into Clickatell's webpage.
Password: the same that use use to login into Clickatell's webpage.
From: enter your own phone number. The one that you authenticated as a valid sender id for your account. If you fail to register any sender id with Clickatell, your message will still be delivered, but with a default sender id.
To: one or more mobile numbers can be entered, separated by a comma. You can either use an international format (with the + sign), or a local number if you set up your clickatell account to automatically convert mobile numbers to International format. A message will be sent out to each of the numbers listed here. Example: +316123456789,6421876543.

Now click on the "Test" button and see what happens.
If no sms message arrives, try to debug the problem by manually sending an sms message via your browser. Use the link:

https://api.clickatell.com/http/sendmsg?user=xxxxxx&password=xxxxxxxx&api_id=xxxxxx&to=15XXXXXXX&text=test&from=13XXXXXXXXX

A successful submission should yield: "ID: (some number)". In case of an error, it will be displayed.

Special characters like æøå and others for SMS

To get special characters transferred correctly from your code and to Clickatell, those shall be translated to Windows-1252.

Example: To use the danish word for kitchen "Køkken" it must be translated in your code to "K%F8kken"

• Example in BLOCKLY: [[1]]

Translation codes can be found here: https://www.w3schools.com/tags/ref_urlencode.asp