Send message - SOAP API

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>