Status reports can be routed back to you via HTTP. HTTP GET is used, and all data are sent as simple query parameters.
You can nominate (in your Profile) whatever URL you wish the status reports to be sent to, e.g.:
http://www.mydomain.dom/reports/deliver.php?pass=blahblah
(yes, please do include a password for use with your receiving script).
You may also want to consider receiving reports on a non-standard port, in an attempt to bypass any transparent proxies between our server and yours, e.g.:
http://www.mydomain.dom:11123/reports/deliver.php?pass=blahblah
Your script is expected to do only one thing reliably: to return at least one character in its output (and of course, not to return an HTTP error code, or a redirect, or anything else other than a 200 response). If your script detects some unexpected input, such as a message id which your system does not know about, or thinks it should not know about, please rather log the fact and return a 200 status, than return a 500 status code which will force us to resubmit the report to you unnecessarily.
If any error occurs during relaying a report to you, such as a network timeout, or your web server returning an HTTP error code, we will attempt to resend the report to you at the following intervals: after 60 minutes, again after another 3 hours, and again after another 12 hours (for a total of 16 hours of retries). Thereafter, the report will not be resent.
Query parameters sent to you:
- msisdn: the number that the original message was sent to.
- batch_id: the id which would have been returned to you if you submitted the message via the send_batch API call, or the send_sms (>= version 2.0) call.
- status: an integer status code for the message.
- completed_time: time that message delivery was completed (only available for some networks). If delivery was successful, this is the time that the message reached the mobile. If not available, the parameter will not be sent at all. The format is yy-MM-dd HH:mm:ss (24 hour clock).
- source_id: your own source_id that you may optionally have submitted in the original message. Use in combination with batch_id if your list of recipients was not unique (e.g. if using send_batch) If not available, the parameter will not be sent at all.
- unique_id: this integer ID must be used to eliminate possible duplicate submissions reaching you, if such duplicates would be problematic for you. Such duplicates can for instance be caused by network congestion, or by your server being slow to return a response. This parameter is always sent.
Any other query parameters that are sent should be ignored.
Possible values for status are:
- 11: Delivered to mobile
- 22: Internal fatal error
- 23: Authentication failure
- 24: Data validation failed
- 25: You do not have sufficient credits
- 26: Upstream credits not available
- 27: You have exceeded your daily quota
- 28: Upstream quota exceeded
- 29: Message sending cancelled
- 31: Unroutable
- 32: Blocked (probably because of a recipient's complaint against you)
- 33: Failed: censored
- 50: Delivery failed - generic failure
- 51: Delivery to phone failed
- 52: Delivery to network failed
- 53: Message expired
- 54: Failed on remote network
- 56: Failed: remotely censored
- 57: Failed due to fault on handset (e.g. SIM full)
- 64: Queued for retry after temporary failure delivering, due to fault on handset (transient)
- 70: Unknown upstream status
If you receive a report with a status code not listed above, please let us know.
|
9-Feb-2010
- Added the unique_id parameter. Removed the deprecated msg_id parameter from documentation (the parameter will still be sent, indefinitely, for backward compatibility).
|
