Callbacks are separated into two categories: delivery status reports and reply messages. Both are signalled back over an HTTP callback to the URLs supplied in the original message request (see Request Body » Outer Level).
Delivery Reports and any other relevant intermediary statuses are posted to the URL specified by the “callback_url” field in the original message request. If no callback_url was specified in the request, no status report callback will be generated. Since more than one delivery report may be obtained from the destination network in a very short time frame, each post request may contain multiple delivery reports bundled together.
For two-way messaging, any reply messages sent by the recipient of the original message will be posted to the URL given by the “reply_url” field in the original message request. If no reply_url is set, two-way messaging will be disabled.
The delivery report and reply-message callbacks generated to these URLs are described below. The endpoints, on the client side, must therefore fully support these kind of requests and respond accordingly.
You may need to configure your firewall to whitelist traffic from these IP addresses:
IPv4: 80.252.167.60
Note that these IPs can change in the future.
HTTP Method: POST
Content-Type: application/json; charset=utf-8
Legend for “Optional” column: N → No; Y → Yes; C → Conditional (see description)
Key | Type | Optional | Description |
---|---|---|---|
api_job_id | String | N | The Job ID generated by the API. This is the same ID that was returned in the response for the request sent in Request Body. |
client_job_id | String | Y | The Job ID supplied by yourself during the original request in Request Body, if supplied. |
data | CALLBACK_INFO[] | N | This contains always at least 1 record. |
Key | Type | Optional | Description | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
type | Enum | N | The channel through which the delivery report originated from.
|
||||||||||||||||||
message_id | String | N | The message ID for this message. This should match the message_id returned in the response detailed in Response. | ||||||||||||||||||
status | Enum | N | Enumeration indicating the message’s state at the moment of the call-back generation. In case of SMS reports, these match the worldwide SMPP v3.4 standard. As for IM networks, extra custom statuses were added to support these new networks.
Statuses for IM extend, not replace, the SMPP standard. Currently, the following statuses can be returned:
|
||||||||||||||||||
timestamp | long | N | UNIX timestamp (i.e. number of seconds from 1 -Jan-1970 in UTC) when the delivery was completed. | ||||||||||||||||||
micro_timestamp | long | N | UNIX micro-timestamp (i.e. number of milliseconds from 1 -Jan-1970 in UTC) when the delivery was completed. | ||||||||||||||||||
to | String | N | Destination mobile number the SMS was sent to. | ||||||||||||||||||
from | String | N | The SMS or IM Sender ID used to send the message. | ||||||||||||||||||
client_message_id | String | Y | The ID originally provided by yourself. | ||||||||||||||||||
error_code | short | N | Error code if an error occurred, or 0 if successful. For a full list of these: http://files.fortytwo.com/api/fortytwo_error_codes.pdf |
When a client receives a callback, the API server expects to receive an HTTP 200 OK. The body of the response is ignored, if this is not empty.
HTTP Method: POST
Content-Type: application/json; charset=utf-8
Legend for “Optional” column: N → No; Y → Yes; C → Conditional (see description)
Key | Type | Optional | Description | ||||
---|---|---|---|---|---|---|---|
api_job_id | String | N | The api_job_id of the original message to which this reply pertains. | ||||
client_job_id | String | Y | The client_job_id of the original message to which this reply pertains, if applicable. | ||||
reply_message_id | String | N | A unique ID assigned to this reply message. Note that while req_uuid is unique for every callback, including retries, a reply_message_id is unique to the message itself. | ||||
orig_message_id | String | Y | The message_id of the original message to which this reply pertains. | ||||
req_uuid | String | N | A UUID generated by Fortytwo’s systems as a unique identifier of every callback made, for traceability and troubleshooting purposes. | ||||
channel | Enum | N | The channel on which the reply originated from. Currently, only VIBER supports two-way messaging.
|
||||
timestamp | long | N | UNIX timestamp (i.e. number of seconds from 1-Jan-1970 in UTC) when the delivery was completed. | ||||
micro_timestamp | long | N | UNIX micro-timestamp (i.e. number of milliseconds from 1-Jan-1970 in UTC) when the delivery was completed. | ||||
from | String | N | The Sender ID of the client replying to the original message. This is typically the client’s mobile number. | ||||
to | String | N | The Sender ID to which this reply is being sent. This is equivalent to the Sender ID used to send the original message. | ||||
message | REPLY_MSG | N | The content of the reply. See REPLY_MSG. |
Key | Type | Optional | Description |
---|---|---|---|
text | String | Y | If the reply message body contains text, this field carries the text sent by the client. |
When a client receives a callback, the API server expects to receive an HTTP 200 OK. The body of the response is ignored, if this is not empty.
The use of SSL on the client’s callback server is optional, i.e. both HTTP and HTTPS schemes are supported. However, if HTTPS validation fails, the callback is treated as failed. For information on how failures are handled, see Callback failure below.
If the client’s server is unreachable or does not return a 200 OK, the callback is queued to be retried again. After three failed attempts, with an interval of 5 minutes between them, the callback is discarded.