ZOLOZZOLOZDOCS

callbacksms

Overview

This document provides detailed callback protocol specifications for ZOLOZ Global SMS service customers. When the final delivery status of your sent SMS 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 final delivery result (i.e., the status report from the carrier), 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 and minutes, depending on the downstream carrier's processing speed and network conditions.

Request

Request Method

Method: HTTP POST

Content-Type: application/json

Request Parameters

Field name

Data type

Mandatory

Description

Sample value

transactionId

String

Y

A unique ID for each SMS send request.

Can also be retrieved via the sendsms API.

"G0062000061MT20230325dAqiXBpQUbVB9h****"

mobile

String

Y

Phone number, including country/region code.

"6212345678901"

status

String

Y

SMS delivered status:

  • Delivered: SMS send successfully.
  • Deliveryfailed: SMS failed to send.

"Delivered"

smsNum

int

Y

Number of SMS messages for billing (see Billing Description).

1

sendDate

String

Y

SMS send time.

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

deliveredDate

String

N

Carrier's confirmation time of successful SMS delivery.

Note: This field is returned only when status is Delivered.

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

Callback Sample

copy
{
    "deliveredDate": "2025-06-30T16:40:56+08:00",
    "mobile": "63123456",
    "sendDate": "2025-06-30T16:35:46+08:00",
    "smsNum": 1,
    "status": "Delivered",
    "transactionId": "G0062000011MT20250630eowLGRE371HnpUHNqM"
}

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 (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 Timout

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.