Callback (push status and cost notification)

What is Push Message Notification?

Push message status notification is a feature of the Clickatell messaging platform that provides updates on the delivery status and charge of your text messages.

Push notifications can be sent via our web API using:

  • HTTP POST / GET
  • XML POST / GET
  • SOAP POST / GET
  • JSON RAW HTTP POST

The status notification indicates whether the message carrier:

  • is still delivering the SMS(intermediary status),
  • has successfully delivered the message (final status)
  • has experienced a send error

How to enable push status notifications

To receive push message status notifications, you must perform a configuration in your Developers' Central account and your server you must follow these steps:

  1. Log in to your Developers' Central account.
  2. From the main menu, select “APIs” and then “Manage APIs” from the submenu. You will be shown a list of all the APIs you currently have assigned to your account.
  3. Select the SMS API you want to configure for push notifications from the list and the click the Edit link.
  4. The Set Up API page will open. Click “Enable your app” to receive message delivery notifications.

– Enter your Callback URL

– Select the method you would like to use to have Clickatell push your delivery status notifications.

Including an authentication header

If you would like to enable an additional level of security, you can specify a callback username and password for you callback URL.

  1. Select the “Include basic HTTP authentication” in the header box.

– Enter your callback username

– Enter your callback password

The configuration of your push status notifications in your Developers' Central account should now be completed.

How the callback URL is validated

The URL entered in your Developers' Central account is validated to check if a callback can be completed. If the callback URL is invalid, a message is displayed indicating an invalid URL.

Callback retry interval

The MT callback system will make eight attempts to deliver a callback to your specified callback URL. The interval for attempts are as follows:

  1. Two minutes after the original attempt
  2. Four minutes after last retry
  3. Eight minutes after last retry
  4. 16 minutes after last retry
  5. 32 minutes after last retry
  6. 64 minutes after last retry
  7. 128 minutes after last retry

If your callback has been queued for three days, any further callback attempts will be stopped.

Types of message statuses returned

You can determine the type of message statuses that you want returned to your callback URL by setting the callback parameter to one of the callback values listed in the table below:

Callback Value

Message status types returned

Message status codes returned

0

No message status returned.

 

1

Returns only intermediate statuses.

003

2

Returns only final statuses of a message.

004, 005, 007, 009, 010, 012

3

Returns both intermediate and final statuses of a message.

003, 004, 005, 007, 009, 010, 012

4

Returns only error statuses of a message.

005, 007, 009, 010, and 012

5

Returns both intermediate and error statuses of a message.

003, 005, 007, 009, 010, 012

6

Returns both final and error statuses of a message.

004, 005, 007, 009, 010, 012

7

Returns both intermediate, final and error statuses of a message.

003, 004, 005, 007, 009, 010, 012

Example API callbacks with Code

The parameters we send are:

Paremeter

Description

api_id

The API ID that was used to send the message.

apiMsgId

The API Message ID of the message.

cliMsgId

The Client Message ID that was set while sending.

timestamp

The time of this status change.

to

The number this message was sent to.

from

The number this message was sent from, if set on submission.

status

The current status of the message.

charge

The cost of the message.

Note all data is URL encoded. It is shown here without URL encoding for visibility.

HTTP GET/POST

Sample URL:

  https://www.yoururl.com/script.asp?api_id=12345&apiMsgId=996f364775e24b8432f45d77da8eca47&cliMsgId=abc123&timestamp=1218007814&to=279995631564&from=27833001171&status=003&charge=0.300000 
 

JSON RAW POST:

Sample data content:

  {
"data": {
"apiId": 105511,
"apiMessageId": "b61bef4ab5aeb2770607c1c49721b440",
"clientMessageId": "",
"timestamp": 1437470173,
"to": "27999044453",
"from": "",
"charge": 2.0,
"messageStatus": "004"
}
}

Sample call:

  POST <your server url> HTTP/1.1
HOST: <your host>
Content-Type: application/json
Accept: /
Content-Length: 188

{"data":{"apiId":105511,"apiMessageId":"b61bef4ab5aeb2770607c1c49721b440","clientMessageId":"","timestamp":1437470173,"to":"27999044453","from":"","charge":2.000000,"messageStatus":"004"}}

XML GET/POST

Sample data content:

<?xml version="1.0"?>
<callback>
	<apiMsgId>996411ad91fa211e7d17bc873aa4a41d</apiMsgId>
	<cliMsgId></cliMsgId>
	<timestamp>1218008129</timestamp>
	<to>279995631564</to>
	<from>27833001171</from>
	<charge>0.300000</charge>
	<status>004</status>
</callback>

Sample URL:

 https://www.yoururl.com/script.php?data=<?xml version="1.0"?><callback><apiMsgId>996411ad91fa211e7d17bc873aa4a41d</apiMsgId><cliMsgId></cliMsg Id><timestamp>1218008129</timestamp><to>279995631564</to><from>27833001171</from><charge>0.30 0000</charge><status>004</status></callback> 

SOAP GET/POST

Sample data content:

<?xml version="1.0" encoding="ISO-8859-1"?>
 <SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:tns="mt_callback">
 	<SOAP-ENV:Body>
		<tns:mt_callback xmlns:tns="mt_callback">
		<api_id xsi:type="xsd:int">1234</api_id>
		<apimsgid xsi:type="xsd:string">2e838df2ee3ea418272ae05aaf84ce5d</apimsgid>
		<climsgid xsi:type="xsd:string">abc123</climsgid>
		<to xsi:type="xsd:string">27999123456</to>
		<from xsi:type="xsd:string">27999000224</from>
		<timestamp xsi:type="xsd:int">1213690834</timestamp>
		<status xsi:type="xsd:int">003</status>
		<charge xsi:type="xsd:float">0.300000</charge>
		</tns:mt_callback>
	</SOAP-ENV:Body>
 </SOAP-ENV:Envelope>

Sample URL:

 http://www.yoursite.com/your_url.php?data="<?xml version="1.0" encoding="ISO-8859-1"?><SOAP- ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP- ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP- ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:tns="mt_callback"><SOAP-ENV:Body> <tns:mt_callback xmlns:tns="mt_callback"><api_id xsi:type="xsd:int">1234</api_id><apimsgid xsi:type="xsd:string">2e838df2ee3ea418272ae05aaf84ce5d</apimsgid><climsgid xsi:type="xsd:string">abc123</climsgid><to xsi:type="xsd:string">27999123456</to><from xsi:type="xsd:string">27999000224</from><timestamp xsi:type="xsd:int">1213690834</timestamp><status xsi:type="xsd:int">003</status><charge xsi:type="xsd:float">0.300000</charge></tns:mt_callback></SOAP-ENV:Body></SOAP- ENV:Envelope>"