Clickatell SMS Gateway How To Guide

From Swivel Knowledgebase
Revision as of 08:33, 12 May 2015 by Gfield (talk)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search


Clickatell

Overview

Clickatell allows SMS messages to be sent by connecting to their SMS gateway. Clickatell support the following connection methods including:

  • HTTP on port 80 (supported by PINsafe)
  • HTTPS on port 443 (supported by PINsafe)
  • SMTP on port 25 (supported by PINsafe through generic SMTP to SMS)
  • SMPP (SMPP is supported by PINsafe but not used for Clickatell)


Prerequisites

Clickatell Account

PINsafe 3.x

Mobile Phone on which to receive SMS text messages


Configuring the Clickatell transport

Clickatell Transport Class

Swivel has two Cliackatell classes for SMS transport:

  • Default menu item, defined as: com.swiveltechnologies.pinsafe.server.transport.ClickatellTransport

The HTTP version Java Class is shipped with Swivel from Swivel version 3.9 onwards. For Swivel versions 3.6 onwards it can be downloaded here ClickatellHttpTransport


Configuring one or more Clickatall transports for PINsafe 3.x

On the PINsafe Administration Console select Transport/General, locate the clickatell transport. Enter the required group name and the number of security strings to be sent.

Identifier: Default: Cliackatell, the name of the transport, must be unique

Class: Default: com.swiveltechnologies.pinsafe.server.transport.ClickatellTransport, the name of the java class used. To create multiple copies of a transport, copy this to a blank field at the bottom of the transport section.

Strings per message: Default: 1, the number of security strings that are sent.

Group: Default: ---NONE--- Where security strings are sent to

Alert repository group: Default: ---NONE--- Where Alert messages are sent to

Destination attribute: Default: phone, the attributes that is read from the data source to determine a users telephone number

Click apply to save the settings. For further information see: Transport Configuration


Configuring the Clickatall details for PINsafe 3.x

Username: Default: blank, Clickatell account name

Password: Default: blank, Clickatell account password

API ID: Default: blank, Clickatell API ID, this is provided by clickatell

Encoding: Default: GSM, Options GSM or UCS2, select if GSM or UCS2 is to be used

Protocol: Default HTTP, Options HTTP or HTTPS, select if SSL is to be used


Troubleshooting

Try sending a security string or alert and check the PINsafe log.

Also see SMS messages are not being sent

Check the connection, use TCP Dump, Wireshark, ethereal or similar to view the connection from PINsafe to the SMS gateway. Look for outbound traffic of HTTP, on port 80, or HTTPS on port 8443 to the SMS Gateway api.clickatell.com.

Can you Telnet to the gateway: telnet api.clickatell.com 80 Press enter and it shoud return an HTTP header.

In 2012 Clickatell changed their IP address to 196.216.236.7 from 196.5.254.66, swivel references the server by hostname api.clickatell.com and if DNS is correctly working then no changes should be required. However check for the presence of a hosts entry specifying the old IP.


How to find the Clickatell API ID:

The API_ID is not the same as the username.

To find the API ID:

1) Log into the clickatell account at http://www.clickatell.com/

2) Click on the 'Product Control' link.

3) Click on the name of the API you want to use.

The API ID will be displayed on the main page. If it is not displayed you will be asked to complete a form after completing the form you will see your API_ID.


Error messages

Clickatell message sending failed, error: org.marre.sms.SmsException: org.marre.sms.transport.clickatell.ClickatellException: Clickatell error. Error 001, Authentication failed

Wrong username, password or API ID for Clickatell SMS account


java.net.ConnectException: connection timed out: connect

or LOG_HTTP_TRANSPORT_ERROR, Connection Timed Out

Connection to Clickatell SMS Gateway failed with the connection timing out. Verify that the PINsafe server connection to the SMS gateway is not being blocked by a firewall or proxy server.


Clickatell message sending failed, error: org.marre.sms.SmsException: Alphanumeric address can be at most 11 chars.

The message may be too long if it includes spaces, dashes and other characters. This can be resolved in the following ways:

  • Ensure mobile numbers are entered without dashes, spaces etc
  • Use the Transport filtering options in PINsafe 3.8


Clickatell message sending failed, error: org.marre.sms.SmsException: org.marre.sms.transport.clickatell.ClickatellException: Clickatell error. Error 108, Invalid or missing api_id

The API ID used in the Clickatell configuration is incorrect.


Clickatell message sending failed, error: org.marre.sms.SmsException: Clickatell error. Error 114, Cannot route message

The phone number has been submitted in the wrong format. Try with country code.