This page requires that you are familiar with the Using the SOAP API page.
The sendmsg
command allows you to send one or more SMS messages. To send messages to your database of mobile numbers, you can call this command in a loop.
The server will respond with a unique identifier for each message (referred to as an API message ID). This API message ID can be used to track and monitor the status of your message. If a message is rejected, an error will be returned.
For high volume messaging, we encourage the use of persistent HTTP/S
connections (keep-alive). Multiple concurrent HTTP/S
connections may also be used for additional performance.
Command
sendmsg
Parameters
In addition to authentication parameters, only to
and text
are required.
Parameter |
Required |
Description |
to |
Yes |
The mobile number to which the message must be delivered. The number should be in international number format (no leading zeros or + symbol should be used). |
text |
Yes |
The text content of the message. Note that some characters take up two character spaces due to GSM encoding standards. |
msg_callback |
No |
Enable message delivery status updates to be sent to your server via an HTTP request. See Callback. |
Many more parameters are available and listed in the send message parameters page.
For compatibility purposes, the callback parameter is named msg_callback
(unlike our other API's). This is because callback
is a built-in parameter in certain versions of Visual Studio.
Examples
All examples below are for the document/literal based server.
Send to two mobile numbers:
<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://api.clickatell.com/soap/document_literal/webservice"> <SOAP-ENV:Body><ns1:sendmsg> <api_id>123456</api_id> <user>MyUserName</user> <password>MyPassword</password> <text>This is my message here!</text> <to>2799900001</to> <to>2799900002</to> </ns1:sendmsg> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
Send a unicode message:
<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://api.clickatell.com/soap/document_literal/webservice"> <SOAP-ENV:Body><ns1:sendmsg> <api_id>123456</api_id> <user>MyUserName</user> <password>MyPassword</password> <text>005400680069007300200069007300200061002000730061006d0070006c00650020006d006500730073006100670065002000730065006e007400200061007300200055006e00690063006f0064006500200064006100740061002e</text> <unicode>1</unicode> <to>2799900001</to> </ns1:sendmsg> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
Send a flash message:
<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://api.clickatell.com/soap/document_literal/webservice"> <SOAP-ENV:Body><ns1:sendmsg> <api_id>123456</api_id> <user>MyUserName</user> <password>MyPassword</password> <text>This is my flash message here!</text> <msg_type>SMS_FLASH</msg_type> <to>2799900001</to> </ns1:sendmsg> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
Send a binary message:
<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://api.clickatell.com/soap/document_literal/webservice"> <SOAP-ENV:Body><ns1:sendmsg> <api_id>123456</api_id> <user>MyUserName</user> <password>MyPassword</password> <udh>0605040B8423F0</udh> <text>040601AE02056A0045C60C037368008503656B732E636F6D0008010374657374000101</text> <to>2799900001</to> </ns1:sendmsg> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
Use callback and sender ID:
<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://api.clickatell.com/soap/document_literal/webservice"> <SOAP-ENV:Body><ns1:sendmsg> <api_id>123456</api_id> <user>MyUserName</user> <password>MyPassword</password> <callback>3</callback> <from>123456789</from> <text>This is my message here!</text> <to>2799900001</to> </ns1:sendmsg> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
Code Samples:
PHP:
<?php $oClient = new SoapClient( 'http://api.clickatell.com/soap/document_literal/webservice?wsdl', array( 'trace' => true, 'keep_alive' => true ) ); $aMobileNumbers = array( '2799900001', '2799900002' ); // Send message $aResult = $oClient->sendmsg( array( 'api_id' => '123456', 'user' => 'MyUsername', 'password' => 'MyPassword', 'text' => 'Hello world', 'to' => $aMobileNumbers ) ); echo '<pre>' . print_r($aResult,true) . '</pre>'; ?>
API Responses
Example response - Sending to two handsets
Successful API response:
<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://api.clickatell.com/soap/document_literal/webservice"> <SOAP-ENV:Body> <ns1:sendmsgResponse> <return>ID: 918c16a73f75530da44c4f17abed80a1 To: 2799900001</return> <return>ID: 8019f2f6e76afc7e421618a4b92e8ec2 To: 2799900002</return> </ns1:sendmsgResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
Error response:
<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://api.clickatell.com/soap/document_literal/webservice"> <SOAP-ENV:Body> <ns1:sendmsgResponse> <return>ERR: 001, Authentication failed To: 2799900001</return> <return>ERR: 001, Authentication failed To: 2799900002</return> </ns1:sendmsgResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
Return format - Single number submission
Successful API response:
ID: <message ID>
Error response:
ERR: <error code>, <error description>