Two-Factor Authentication REST API

Callbacks

Home » API » Two-Factor Authentication REST API » Callbacks

Callbacks

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.

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

An HTTP request is sent to the specified callback_url with the SMS delivery details in the JSON body, ex:

{
  "api_job_id": "0c6ccf37-dd15-49ff-a12f-ffad8f2655a6"",
  "client_job_id": "",
  "data": [
    {
      "type": "SMS",
      "message_id": "14466445287300014003",
      "status": "DELIVRD",
      "timestamp": 1443165174145,
      "micro_timestamp": 1443165174145000,
      "to": "35699XXXXXX",
      "sms_from": "Fortytwo",
      "viber_from": "",
      "client_message_id": "reference1",
      "error_code": 943
    }
  ]
}

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

 

SSL Support

The use of SSL on the callback receiver 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.

 

Callback response outer 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 Section Request code – Response Description.
client_job_id String Y The Job ID supplied by the client during the original request in Section Request Body. If this field was not supplied, it will not be returned here either.
data CALLBACK_INFO[] N This contains at least 1 record.

 

Callback response – data array description

Key Type Optional Description
type Enum

N

 The type of network through which the delivery report originated from.

Enum Description
INTERNAL Initial phase of the request
SMS SMS Network
VIBER IM Service on Viber Network
message_id String

N

 The message ID for this message. This should match the message_id returned in the response detailed in  Section Request code – Response Description
status Enum

N

 Enumeration indicating the message’s state at the moment of the callback 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:

Enum Description
ACCEPTD Message has been accepted.
DELIVRD Message is delivered to destination.
EXPIRED Message validity period has expired.
DELETED Message has been deleted.
UNDELIV Message undeliverable.
REJECTD Message rejected.
UNKNOWN Message is in an invalid state.
SEEN Message seen by the user on device
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

 Mobile number the SMS was sent to.
Number is in international format and can only be digits between 7-15 digits long. The first digit cannot be a 0.
from String

N

 The sender of the SMS.
If numerical: Contains only digits, between 1-15 digits long.
If alphanumerical: A maximum of 11 characters and minimum of 1 character.
client_message_id String

Y

 The ID originally generated by the client. Maps the original request by the client with the callback, using the client’s own ID.
Minimum length of 1 characters.
error_code short

N

 Error code, else 0.
For a full list of these codes, http://files.fortytwotele.com/api/Fortytwo_Telecom_error_codes.pdf

 

Callback response by client

When a client receives a callback, the Fortytwo API server expects to receive an HTTP 200 OK. The body of the response is ignored, if this is not empty.

 

Callback failure

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.

Get Started