Trader System Limited
Trader Systems Limited
3 Uplands Road
Caversham
Reading
RG4 7JG
United Kingdom
Tel +44(0) 118 375 9065

Clickatell XML API with PHP

I spent some little time trying to follow the Clickatell XML API v2.2.6 specification (and a number of fruitless emails to Clickatell Support - "We don't support developers"...) to get the interface working from PHP.

My initial attempts always resulted in:

<?xml version="1.0" ?>
<clickAPI>
<xmlErrorResp>
<fault>XML error: no element found at line 1</fault>
</xmlErrorResp>
</clickAPI>

The interface uses a non-standard XML format and I found the manual is somewhat confusing. The code below shows how to call the interface (without error handling for simplicity) from PHP using CURL. Basically the XML declaration is dropped, no encoding, and the whole thing is wrapped in the string data="your xml here". Not rocket science but not clear from reading the specification.


<?php
  // (c) TRADER SYSTEMS LIMITED 2006
  //
  $url='http://api.clickatell.com/xml/xml'; // https appears to work too.
  $api_id='1234567'; // your XML API api Clickatell ID
  $username='username';
  $pw='password';
  $from='tradersystems'; // max 11 characters


  $to='447123456789'; // international format mobile number...

  $smsmsg='This is a test SMS message';


  // htmlentities would be useful to ensure sms contains valid characters...

  // truncate if over size message
  if (strlen($smsmsg)>160){
    $smsmsg=left($smsmsg,160);
    }


  // Assemble the SMS msg
  // Note no <?xml version=....
  // Note add data= around whole XML snippet

  $myXMLmsg = '';
  $myXMLmsg .= 'data="';
  $myXMLmsg .= '<clickAPI>';
  $myXMLmsg .= '<sendMsg>';
  $myXMLmsg .= '<api_id>' . $api_id . '</api_id>';
  $myXMLmsg .= '<user>' . $username . '</user>';
  $myXMLmsg .= '<password>' . $pw . '</password>';
  $myXMLmsg .= '<to>' . $to . '</to>';
  $myXMLmsg .= '<text>' . $smsmsg . '</text>';
  $myXMLmsg .= '<from>' . $from . '</from>';
  $myXMLmsg .= '</sendMsg>';
  $myXMLmsg .= '</clickAPI>"';


  // Start CURL session
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_HEADER, 0);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
  curl_setopt($ch, CURLOPT_VERBOSE, 0);
  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $myXMLmsg);

  $buffer = curl_exec($ch);
  if (!curl_errno($ch)) {
     // CURL sent OK - check response XML in $buffer that everything was received OK
     // $buffer looks something like:
     // <?xml version="1.0">
     // <clickAPI>
     // <sendMsgResp>
     // <apiMsgId>1234567890abcdef...</apiMsgId>
     // </sendMsgResp>

     // </clickAPI>

  }
  curl_close($ch);

 }

 ?>

The specification implies that the preferred way to send messgae is to first send the auth messge with username, password and api_id to receive a session_id which is then used in your subsequent calls to sendMsg etc. Whilst this makes sense for multiple message sending and gives some level of username and passord obscuring over http, you may also call the interfaces by replacing tag session_id with tags api_id, user, password (again the specification is unclear on this).

Any comments or suggestions to info@tradersystems.co.uk.

Trader Systems Limited provides consultancy to large and small firms in the UK and mainland Europe. Call 0118 375 9065 for more information.