ZOLOZZOLOZDOCS

CallbackMessage

This document provides detailed callback protocol specifications for ZOLOZ Global Chatapp service. When the final delivery status of your sent Chatapp (i.e., Whatapp, Viber) changes (e.g., successfully delivered or failed to send), ZOLOZ will actively push the status report to your pre-configured callback URL via an HTTP request.

Callback Mechanism

When the SMS sending task receives a official return result (i.e., Whatapp or Viber), ZOLOZ will immediately push this status information to your configured callback URL.

Note: This is an asynchronous process. The time interval between a successful API call and receiving the callback may range from seconds to minutes, depending on the Viber processing speed and network conditions.

Request

Request Method

  • Method: HTTP POST
  • Content-type: application/json

Request parameter

Field name

Data type

Mandatory

Description

Sample value

channelType

String

Y

Channel type. The fixed value is VIBER.

"VIBER"

transactionId

String

Y

Unique Message Delivery ID. Obtainable via the SendMessage API.

"G0062000061MT20230325dAqiXBpQUbVB9h****"

mobile

String

Y

Recipient phone number. The format is International dialing code + number.

"6321245567****"

status

String

Y

Message delivery status.

  • Delivered: Message sent successfully.
  • DeliveryFailed: Message delivery failed.
  • Read: Message read.
  • Sent: Message sent.

"Delivered"

sendNum

Int

Y

Number of messages for billing.

1

sendDate

String

Y

Message send time.

"2024-03-14T20:26:22+08:00"

deliveredDate

String

N

Delivery receipt time.

Note: This parameter is only valid when the status is set to Delivered.

"2024-03-14T20:26:36+08:00"

readDate

String

N

Message read time.

"2024-03-14T20:26:36+08:00"

errorCode

String

N

Message send failure code.

"ERROR"

errorMsg

String

N

Message send failure description.

"ERROR"

Callback Sample

copy
{
    "channelType": "VIBER", 
    "transactionId": "G0062000061MT20230325dAqiXBpQUbVB9h****", 
    "mobile": "6321245567****", 
    "Status": "Delivered", 
    "sendNum": 1, 
    "sendDate": "2024-03-14T20:26:22+08:00", 
    "deliveredDate": "2024-03-14T20:26:36+08:00", 
    "readDate": "2024-03-14T20:26:36+08:00", 
    "errorCode": "ERROR", 
    "errorMsg": "ERROR"
}

Response

To confirm that you have successfully received the callback notification, your server interface must return the following response.

Success Response

HTTP Status Code: 200 OK
Note: The ZOLOZ system considers HTTP Status Code of 200 as the only criterion for a successful callback. The response content is for your internal debugging purposes only.

Failure Response

If your system returns any HTTP Status Code other than 200 OK (or if a network timeout occurs), the ZOLOZ system will treat the callback as failed and trigger a retry mechanism.

Retry Mechanism

To ensure reliable delivery of callback messages, the system will automatically retry if your interface does not return 200 OK.

Parameter

Value

Description

Max Retry Attempts

10 times

Total of 10 attempts (1 initial + 9 retries).

Retry Interval

5 seconds

Retries every 5 seconds.

Request Timeout

3 seconds

Timeout for connecting to and reading your interface.

The system will stop retrying when any of the following conditions is met:

  1. The interface successfully returns 200 OK.
  2. All 10 retry attempts are exhausted. Afterward, the system will no longer push this status report.

Idempotency Check

Duplicate callbacks may occur due to network issues. Receivers can perform idempotency checks using the transactionId to avoid processing duplicates.