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:
- Log in to your Developers’ Central account.
- 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.
- Select the SMS API you want to configure for push notifications from the list and then click the Edit link.
- 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 your callback URL.
- 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:
- Two minutes after the original attempt
- Four minutes after last retry
- Eight minutes after last retry
- 16 minutes after last retry
- 32 minutes after last retry
- 64 minutes after last retry
- 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:
|
Parameter |
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×tamp=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:
|
1 |
|
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:
|
1 |
|
Sample URL:
http://www.yoursite.com/your_url.php?data="<?xml version="1.0" encoding="ISO-8859-1"?><SOAP- ENV:Envelope SOAP-ENV:encodingStyle="ht |
Submit a Comment
Other Resources
Ask the Community
Visit Stack Overflow to join our community of developers and find the answer you need
Contact Support
Contact our support team and one of our agents will be in touch with you to answer any questions you have