Loader

PHP library

 

Overview

Use Clickatell’s PHP library with our HTTP or REST messaging APIs to interact with the Clickatell SMS Gateway.

Get PHP library


When to use this

Used by web-based clients to send SMS alerts and notifications. After signing up, use this PHP library to include in your project.


Installation

This library uses composer and can be acquired using the following in your composer.json file.

{
    "require": {
        "arcturial/clickatell": "*"
    }
}

 

Usage

The library currently supports the ClickatellHttp and ClickatellRest adapters.


HTTP API
use Clickatell\Api\ClickatellHttp;
  
$clickatell = new ClickatellHttp($username, $password, $apiID);
$response = $clickatell->sendMessage(array(1111111111), "My Message");
  
foreach ($response as $message) {
    echo $message->id;
      
    // Message response fields:
    // $message->id
    // $message->destination
    // $message->error
    // $message->errorCode
  
}

 

REST API
use Clickatell\Api\ClickatellRest;
  
$clickatell = new ClickatellRest($token);
$response = $clickatell->sendMessage(array(1111111111), "My Message");
  
foreach ($response as $message) {
    echo $message->id;
  
    // Message response fields:
    // $message->id
    // $message->destination
    // $message->error
    // $message->errorCode
  
}

 

Sending to multiple numbers

The sendMessage call to parameter can take an array of numbers. If you specify only a single number e.g.:

$clickatell->sendMessage(1111111111, "Message")

the library will automatically convert it to an array for your convenience.

 

Supported API calls

The available calls are defined in the Clickatell\TransportInterface interface.

public function sendMessage($to, $message, $extra = array());
  
public function getBalance();
  
public function stopMessage($apiMsgId);
  
public function queryMessage($apiMsgId);
  
public function routeCoverage($msisdn);
  
public function getMessageCharge($apiMsgId);

 

Events

The library comes with a ClickatellEvent class that is a wrapper for any of the other transports. This class can assist you with debugging or logging API interactions.

This class uses the Proxy Pattern.

<?php
  
use Clickatell\Api\ClickatellHttp;
use Clickatell\ClickatellEvent;
use Clickatellvent;
  
$clickatell = new ClickatellHttp($username, $password, $apiID);
$event = new ClickatellEvent($clickatell);
  
$event->onRequest(function ($event, $args) {
  
    var_dump($event);
    var_dump($args->to);
    var_dump($args->message);
    var_dump($args->extra);
  
    // The parameters in the event object depend on the type of event.
    // The event constants are available in the Clickatellvent class.
  
});
  
$event->onResponse(function ($event, $obj) {
  
var_dump($event);
var_dump($obj);
  
// The $obj variable is the same as the response you would get back. So
// in the case of sendMessage it will be an array of message responses.
  
});
  
$event->sendMessage(array(1111111111), "My Message");
  
?>

 

Dealing with extra parameters in sendMessage

For usability purposes the sendMessage call focuses on the recipients and the content. In order to specify any of the additional parameters defined in the Clickatell document, you can use the extra parameter and pass them as an array.


Callbacks

You can listen to Clickatell callbacks by using the Callback::parseCallback(); function. It’s a helper function to make sure the required parameters are included in the $_GET array.

Parameters: apiMsgId, cliMsgId, to, timestamp, from, status, charge

Example:

use Clickatell\Callback;
  
Callback::parseCallback(function ($values) {
    // var_dump($values);
    // Contains: apiMsgId, cliMsgId, to, timestamp, from, status, charge
});
  
?>

 

OTP/Two-Factor Authentication

The library has built-in support for sending OTPs (One Time Pins) to verify the identity of a user. This is helpful as a second step during authentication or to validate that the person you are interacting with is a real entity.

use Clickatell\Otp\SessionStorage;
use Clickatell\Otp\ClickatellOtp;
use Clickatell\Api\Rest;
  
// Define the OTP storage mechanism. Passing "true" means
// a new session will forcibly started.
$storage = new SessionStorage(true);
$api = new Rest([token]);
  
$otp = new ClickatellOtp($api, $storage);
  
$otp->setMessage("My custom OTP message. OTP here %s"); // The %s will be replaced with the token.
  
$otp->sendPin([number]); // Passing a second argument will assign a unique reference to the token.
  
...
  
// If you passed a second argument while sending the pin, you must now pass it as a third argument.
// The token is the pin you received via SMS. This step is usually done on a form submit.
  
$return = $otp->verifyPin([number], [token]);
  
// $return = true OR false

 

Symfony Bundle

In order to start using the bundle, you first need to register it within your AppKernel.php

class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
            ...
            new Clickatell\Symfony\ClickatellBundle()
        );
          
        return $bundles;
    }
}

 

You also need to specify your Clickatell credentials in your application config. In this example, YAML is used.

clickatell:
    class: Clickatell\Api\ClickatellHttp
    arguments: [ "username", "password", "api_id" ]

 

The ‘class’ parameter

The class parameter can be any class that inherits from Clickatell\Clickatell. The default value for this is Clickatell\Api\ClickatellHttp.


The ‘arguments’ parameter

This parameter will be the constructor arguments for your class. What you specify here will depend on what your class takes as constructor arguments.

  • The Clickatell\Api\ClickatellRest class takes one argument – your API token (issued by Clickatell)
  • The Clickatell\Api\ClickatellHttp class takes three arguments – your username, password and API ID (issued by Clickatell)

The bundle usage

Once you have configured the component, you can utilize it in your controllers as shown below: 

class DefaultController extends Controller
{
    public function indexAction()
    {
        ...
          
        $clickatell = $this->get('clickatell');
        $response = $clickatell->sendMessage(["number", "number2"], "My Text Message");
  
        ...
    }
}

 

You can see our other libraries and more documentation at the Clickatell APIs and Libraries Project.

Channels

Find the most up-to-date information about the channels available to communicate with your clients.

Find Out More >
SDKs

Documentation
Bulk SMS Scripts

Documentation
SMS

Enable any application, website or system to facilitate local or international one- or two-way SMS communication via an easy one-step integration with our HTTP API.

Documentation
One API

Communicate with your mobile customers via multiple communication channels with a single integration. You can send and receive messages on both WhatsApp and SMS without the overhead of programming individual channels.

Documentation
WhatsApp

As an authorized WhatsApp Business Solution Provider, we assist you in applying for a WhatsApp Business account and number. Integrate with other powerful features available on our platform via our One API.

Documentation

Products

Find the most up-to-date information about the products we offer and how to elevate your engagement with customers.

Find Out More >
Chat 2 Pay

Send payment requests to customers via chat for secure, contactless payment experiences.

Documentation
Chat Desk

An easy-to-use web-based application that enables real-time communication with your customers via a single web interface.

Documentation
Chat Flow

A web-based application that allows you to quickly and collaboratively design and deploy conversational experiences across multiple chat applications and connect it to your organization's core functional APIs.

Documentation
Campaign Manager

An online tool that allows you to create a custom SMS campaign within minutes - no coding or developers required.

Documentation

Marketplace

Find the most up-to-date information about Clickatell's Marketplace and how you can utilize it for the distribution and payment acceptance of digital products.

Find Out More >
Bank Interfaces API

An explanation of the way Clickatell and banks interact with one another when dealing with purchases. 

Documentation
Transact Result API

Initiates the delivery of the transaction result for a purchase that was made through Clickatell after Clickatell facilitated the dispensing of the product.

Documentation
Reserve and Transact API

Initiates a purchase and fund reservation request to Clickatell.

Documentation
Security Service API

Request authentication tokens to use in all other Clickatell API calls.

Documentation
Transact

A cloud-based platform that allows for the distribution and payment acceptance of multiple digital products.

Documentation
Product Lookup API

Confirm a product's configuration and attributes.

Documentation
In-Flight Transaction Check API

Used prior to a purchase instruction to confirm that no similar transaction is in progress.

Documentation
User Transaction Lookup API

Identify if a new transaction is similar to one of the user's recent transactions so the response details can be used to pre-emptively complete the current transaction details.

Documentation
Customer Account Validation API

Validate a customer's bill payment account number prior to submitting the bill payment purchase request to the vendor.

Documentation
MNO Lookup API

Derive the specific mobile network operator (MNO) for the specified MSISDN.

Documentation
Token Lookup API

Look up tokens/vouchers to present back to the buyer/customer who purchased token-related products via Clickatell's platform.

Documentation
Notifications API

Send notifications to buyer/recipient using different channels.

Documentation
Transaction Lookup API

Used after a purchase to confirm the transaction status.

Documentation
Financial Terms Lookup API

Display the correct fee and settlement amounts as per the contractual agreement for the SKU being purchased.

Documentation
Transact API

Initiates a purchase request to Clickatell.

Documentation

Other Resources

Ask the Community

Visit Stack Overflow to join our community of developers and find the answer you need

Visit Stack Overflow >

Contact Support

Contact our support team and one of our agents will be in touch with you to answer any questions you have

Contact Support >