Comprehensive Clickatell SMS Cheatsheet: APIs, Integration & Best Practices

Introduction to Clickatell SMS

Clickatell is a leading global SMS communications platform that enables businesses to send and receive text messages across multiple channels worldwide. Founded in 2000, Clickatell provides APIs and services for SMS, WhatsApp, and other messaging channels with reliable delivery in over 220 countries and territories. Clickatell’s platform offers programmable messaging capabilities, enabling companies to integrate real-time communications into their applications, websites, and business processes for marketing, customer service, authentication, notifications, and alerts.

Core Clickatell SMS Concepts

Clickatell Account Setup Process

1. Account Creation

• Visit Clickatell Portal
• Register for a new account with business details
• Verify email address
• Complete business verification process if required

2. Integration Setup

• Select integration type (API, Two-way, WhatsApp, etc.)
• Generate API credentials
• Configure callback URLs for delivery reports
• Set default sender ID/from number (where applicable)

3. Billing Configuration

• Add payment method
• Purchase message credits or set up subscription
• Configure low-balance alerts
• Set up usage reports and notifications

4. Testing Environment

• Use test credentials in sandbox environment
• Verify basic connectivity
• Test message delivery and callbacks
• Validate character encoding and message formatting

Clickatell API Options Comparison

REST API Implementation

Authentication

Authorization: Bearer {your_api_key}
Content-Type: application/json
Accept: application/json

Send SMS Example

// Using fetch API in JavaScript
fetch('https://platform.clickatell.com/messages', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {your_api_key}'
  },
  body: JSON.stringify({
    'content': 'Your message here',
    'to': ['1234567890', '2345678901'],
    'from': 'CompanyName'
  })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Check Message Status

GET https://platform.clickatell.com/messages/{apiMessageId}
Authorization: Bearer {your_api_key}

Get Account Balance

GET https://platform.clickatell.com/public-client/account/balance
Authorization: Bearer {your_api_key}

HTTP API Implementation

Send SMS Example

GET https://platform.clickatell.com/messages/http/send?apiKey={api_key}&to=1234567890&content=Your+message+here&from=CompanyName

Check Delivery Status

GET https://platform.clickatell.com/messages/http/status?apiKey={api_key}&messageId={message_id}

Check Account Balance

GET https://api.clickatell.com/http/getbalance?api_id={api_id}&user={username}&password={password}

Message Parameters & Formatting

Essential Parameters

• to: Recipient number(s) in international format (1234567890)
• content: Message text (max 160 chars for standard SMS)
• from: Sender ID or number (subject to country regulations)
• callback: URL for delivery notifications (optional)
• clientMessageId: Your reference ID (optional)
• deliveryAcknowledgement: Request for delivery reports (true/false)

Character Limits

• Standard SMS: 160 characters (GSM-7 encoding)
• Unicode SMS: 70 characters (UCS-2 encoding)
• Concatenated SMS: Multiple SMS segments (up to 918 characters in GSM-7)
• Binary SMS: 140 bytes per message

Character Set Handling

• GSM-7 alphabet for standard Latin characters
• UCS-2 encoding for Unicode characters (non-Latin alphabets)
• Automatic detection of required encoding
• Special characters like ^{}[]~|€ count as two characters in GSM-7

Two-Way Messaging Setup

1. Enable Two-Way Messaging

• Request a dedicated number from Clickatell
• Configure in portal under Two-Way settings
• Set callback URL for incoming messages

2. Callback Integration

// Example Express.js webhook handler for incoming messages
app.post('/sms/incoming', (req, res) => {
  const { from, text, messageId, timestamp } = req.body;
  console.log(`Message from ${from}: ${text}`);
  // Process incoming message
  res.status(200).send('OK');
});

3. Reply to Incoming Messages

// Using the same REST API with the dedicated number
fetch('https://platform.clickatell.com/messages', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {your_api_key}'
  },
  body: JSON.stringify({
    'content': 'Your reply message',
    'to': [incomingFrom],
    'from': 'YourDedicatedNumber'
  })
})

Delivery Reports & Callbacks

Delivery Statuses

• Accepted: Message accepted for delivery
• Delivered: Successfully delivered to recipient
• Failed: Delivery failed (with error code)
• Rejected: Message rejected (invalid format, blocked, etc.)
• Expired: Message could not be delivered within validity period
• Queued: Message queued for delivery

Callback Format

{
  "messageId": "a28d9ce06648468d96c35be7b820dec0",
  "clientMessageId": "abc-123",
  "to": "27841234567",
  "from": "ACME Inc",
  "status": "DELIVERED",
  "statusDescription": "Message delivered to handset",
  "timestamp": "2023-05-18T12:34:56Z"
}

Setting Up Callbacks

• Configure default callback URL in portal
• Override per message with callback parameter
• Ensure endpoint responds with HTTP 200 OK
• Implement retry logic to handle temporary failures

SMS Templates & Content Best Practices

Template Structure

Hi {name}, your {service} appointment is confirmed for {date} at {time}. Reply YES to confirm or call {phone} to reschedule.

Compliance Requirements

• Include opt-out instructions (“Reply STOP to unsubscribe”)
• Identify your business clearly
• Follow local regulations (TCPA, GDPR, POPIA, etc.)
• Obtain explicit consent before messaging
• Honor opt-out requests immediately

Content Optimization

• Keep messages concise (under 160 characters when possible)
• Place critical information at the beginning
• Include clear call-to-action
• Use personalization to increase engagement
• Avoid ALL CAPS (appears spammy and uses more characters)
• Test links before sending
• Consider time zones when scheduling

Common Challenges & Solutions

Clickatell SDKs & Code Examples

PHP SDK

<?php
require_once 'vendor/autoload.php';

use Clickatell\Rest;
use Clickatell\ClickatellException;

$clickatell = new Rest('YOUR_API_KEY');

try {
    $result = $clickatell->sendMessage(['to' => ['27641234567'], 'content' => 'Message content']);
    print_r($result);
} catch (ClickatellException $e) {
    echo $e->getMessage();
}

Java SDK

import com.clickatell.platform.ClickatellRestClient;
import com.clickatell.platform.Message;
import com.clickatell.platform.response.SendMessageResponse;

public class SendSmsExample {
    public static void main(String[] args) {
        ClickatellRestClient client = new ClickatellRestClient("YOUR_API_KEY");
        
        Message message = new Message.Builder()
            .withContent("Hello World!")
            .withTo("27641234567")
            .withFrom("CompanyName")
            .build();
            
        try {
            SendMessageResponse response = client.sendMessage(message);
            System.out.println(response.getData().get(0).getMessageId());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Python Example

import requests
import json

url = "https://platform.clickatell.com/messages"
headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
}
payload = {
    'content': 'Hello World!',
    'to': ['27641234567'],
    'from': 'CompanyName'
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
print(response.json())

C# Example

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

class Program
{
    static async Task Main()
    {
        var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_API_KEY");
        
        var payload = new
        {
            content = "Hello World!",
            to = new[] { "27641234567" },
            from = "CompanyName"
        };
        
        var jsonContent = new StringContent(
            JsonConvert.SerializeObject(payload),
            Encoding.UTF8,
            "application/json"
        );
        
        var response = await client.PostAsync(
            "https://platform.clickatell.com/messages",
            jsonContent
        );
        
        var result = await response.Content.ReadAsStringAsync();
        Console.WriteLine(result);
    }
}

Advanced Features & Integration

Bulk Messaging

• Use arrays of recipient numbers (up to 100-1000 per request)
• Implement batching for very large campaigns
• Consider throughput rates and timing
• Use clientMessageId for tracking
• Schedule delivery during optimal hours

WhatsApp Integration

• Connect Clickatell One API for unified messaging
• Use rich media content where appropriate
• Implement fallback to SMS when WhatsApp unavailable
• Follow WhatsApp Commerce Policy guidelines
• Use approved message templates

SMS Campaign Management

• Leverage analytics dashboard for campaign insights
• Segment audiences for targeted messaging
• A/B test message content
• Track conversion rates with UTM parameters
• Implement unsubscribe management

Security Best Practices

• Store API keys securely (environment variables, secret management)
• Implement IP whitelisting where available
• Use HTTPS for all API communications
• Validate input/output data
• Audit SMS usage regularly
• Rotate API credentials periodically

Best Practices & Tips

Technical Implementation

• Implement exponential backoff for retries
• Use asynchronous processing for high-volume sending
• Validate phone numbers before sending
• Keep track of opt-out status in your database
• Implement proper error handling with logging
• Test with small batches before large campaigns
• Cache frequently used API responses (balance, etc.)

Content & User Experience

• Send during business hours (respect time zones)
• Keep frequency appropriate (avoid over-messaging)
• Make messages actionable and valuable
• Personalize content when possible
• Include clear identification of sender
• Provide easy opt-out mechanisms
• Test full user journey (including links)

Compliance & Regulations

• Maintain clear consent records
• Update privacy policy to reflect SMS usage
• Follow country-specific regulations
• Implement mandatory opt-out handling
• Stay updated on telecom regulations
• Register sender IDs where required
• Keep message content compliant with carrier policies

Resources for Further Learning

Official Clickatell Resources

• Clickatell Developer Central
• API Documentation
• Clickatell Status Page
• Clickatell GitHub Repositories
• Clickatell Support Knowledge Base

Tutorials & Guides

• Getting Started with SMS API
• Two-Way Messaging Setup Guide
• SMS Compliance Best Practices
• Advanced SMS Integration Patterns
• Clickatell Platform Migration Guide

Community & Support

• Clickatell Support Portal
• Clickatell Developer Forums
• Stack Overflow Clickatell Tag
• Clickatell Webinars & Events
• Support Email: support@clickatell.com
• Developer Support: support@clickatell.com with “Developer Support” in subject

This cheatsheet provides a comprehensive overview of Clickatell SMS integration. For the most current information, always refer to the official Clickatell documentation as APIs and features may change over time.