Delivery reports and any other relevant intermediary status are signalled back to the client using an HTTP callback. The URL invoked is obtained from the “callback_url” field in the original message request (see Request Body » Outer Level).

The request generated to this URL is described here. The endpoint on the client side, must fully support this kind of request and respond accordingly.

If a callback_url was not specified in the request, a callback is not generated.

Each request can contain one or more delivery reports bundled together, since more than one delivery report is obtained from the destination network in a very short time frame.

Callback Request

Whitelist callback server

You may need to configure your firewall to whitelist traffic from these IP addresses:
Please note that these IPs can change in the future.

Request Body

Content-Type: application/json; charset=utf-8

JSON Parameters

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 applicable.
data CALLBACK_INFO[] N This contains always at least 1 record.


Key Type Optional Description
type Enum N The type of network through which the delivery report originated. This is a constant and does not change; provided for compatibility with future integration with IM Gateway.

Enum Description
SMS SMS Network
message_id String N The message ID for this message. This matches the message_id returned in the response detailed in Response.
status Enum N Enumeration indicating the message’s state at the moment of the callback generation. For SMS, these match the worldwide SMPP v3.4 standard. Currently, the following statuses can be returned:

Enum Description
DELIVRD Message is delivered to destination.
EXPIRED Message validity period has expired without delivery.
DELETED Message has been deleted without delivery.
UNDELIV Message undeliverable.
REJECTD Message rejected.
UNKNOWN Message is in an invalid state.
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 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:

Callback response by 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.

SSL Support

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 informatio below.

Callback failure

If the client’s server is unreachable or does not return a 200 OK, the callback is queued for retry. After three failed attempts, with an interval of 5 minutes between them, the callback is discarded.

Get Started