The HTTP push API allows incoming SMSs, including replies to outgoing SMSs, to be routed back to you via HTTP. HTTP GET is used, and all data is sent as simple query parameters.
You can nominate (in your Profile) whatever URL you wish the incoming messages to be sent to, e.g.:
http://www.mydomain.dom/incoming/deliver.php?pass=blahblah
(yes, please do include a password for use with your receiving script).
You may also want to consider receiving replies 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/incoming/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 (OK) response). Any HTTP response other than a 500 (Internal Server Error) will be considered to be a fatal error, and not retried. Please trap your errors: if your script generates a SQL error (e.g. because you are encountering a certain type of character in a message body for the first time), 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.
| parameter | description |
|---|---|
| msisdn | the number that the incoming message was sent to. |
| sender | the number that the incoming message was sent from. |
| message | the message sent (can be empty): 0-160 characters. |
| dca | the message content type, being one of: 7bit/8bit/16bit. For 8bit (binary SMS) and 16bit (Unicode SMS), message will be encoded as a hex string, e.g. 004200430044060006010602. |
| msg_id | an integer identifier unique to this incoming message. You must use this to eliminate possible duplicate submissions reaching you, if such duplicates would be problematic for you. |
| source_id | if this message is in reply to a message previously sent, will be set to the source_id of the original message that was sent. |
| referring_batch_id | the integer identifier that was returned by the send_sms api call at the time when the original message was submitted, if this message is in reply to another previously sent. If this incoming message is not a reply, this field will be set to zero. This field replaces referring_msg_id for newer versions of send_sms. |
| referring_msg_id | the integer identifier that was returned by the send_sms api call (versions < 2.0) at the time when the original message was submitted, if this message is in reply to another previously sent. If this incoming message is not a reply, this field will be set to zero. |
| network_id | the mcc+mnc tuple identifying the cellular network that this message belongs to - useful for detecting ported numbers (this information is not always available - an empty string is set if not determinable). |
| concat_reference | the concatenated reference number (only present for concatenated messages). (values: 0-255) |
| concat_num_segments | the total number of messages within the concatenated set (only present for concatenated messages). (values: 1-255) |
| concat_seq_num | the sequence number of this message within the concatenated set (only present for concatenated messages). (values: 1-255) |
| received_time | the time that the message was received, relative to the time zone set in your Profile. Format: yyyy-MM-dd HH:mm:ss (24 hour clock). |
Any other query parameters that are sent should be ignored.