Chuyển tới nội dung chính

Message Status Webhook

Instructions for building a webhook to receive message status updates.

🌐 Webhook URL​

You need to provide us with your Webhook URL to receive message status notifications.

Example URL:

https://your-domain.com/webhook

📦 Data Structure Sent to the Webhook​

  • Method: GET
  • Timeout: 2 seconds

The parameter structure sent depends on how the message was sent: single send (sending individual messages) or batch send (sending in bulk).


1️⃣ Case: Single Send​

ParameterMeaningData Type
msg_idmsg_id returned when sending the message via APIString
statusMessage status (success, failed)String
error_codeError code (if any)String / Null

CURL Example:

curl -X GET "https://your-domain.com/webhook?msg_id=8a4938af-eef9-462f-b9aa-06b7520039c9&status=success&error_code=null"

Example data (JSON format, for reference on structure):

{
"msg_id": "8a4938af-eef9-462f-b9aa-06b7520039c9",
"status": "success",
"error_code": null,
}

2️⃣ Case: Batch Send​

ParameterMeaningData Type
msg_idmsg_id returned when sending the message via APIString
statusMessage status (success, failed)String
error_codeError code (if any)String / Null
phoneRecipient phone number (format 84x)String
tracking_idTracking ID included with each item in the data array when calling the batch send APIString

CURL Example:

curl -X GET "https://your-domain.com/webhook?msg_id=8a4938af-eef9-462f-b9aa-06b7520039c9&status=success&error_code=null&phone=84394375407&tracking_id=3b3285e0-e4b9-4ace-a8fc-d131d0b4f9de"

Example data (JSON format, for reference on structure):

{
"msg_id": "8a4938af-eef9-462f-b9aa-06b7520039c9",
"status": "success",
"error_code": null,
"phone": "84394375407",
"tracking_id": "3b3285e0-e4b9-4ace-a8fc-d131d0b4f9de"
}

✅ Response​

  • HTTP Code: 200 OK
  • The webhook returning HTTP_CODE 200 is considered successful
  • Error code list: Here

🛡️ Webhook Security​

  • IP Authentication: Only whitelisted IPs from our system are accepted.

📌 Notes​

  • If the webhook call fails, we will retry 2 more times, 30 seconds apart.
  • The webhook response time must be less than 2 seconds. If it exceeds 2 seconds, it is considered a failure.
  • tracking_id only appears for the batch send case, and is the same as the client_message_id you include with each message when calling the bulk send API, used to reconcile the status of each specific message.