Webhook Trạng Thái Tin Nhắn

Hướng dẫn xây dựng webhook nhận trạng thái tin nhắn

🌐 URL Webhook

Bạn cần cung cấp URL Webhook cho chúng tôi để nhận trạng thái tin nhắn.

Ví dụ URL:

https://your-domain.com/webhook

---

📦 Cấu Trúc Dữ Liệu Gửi Đến Webhook

• Phương thức gửi: GET
• Timeout: 2 giây

Cấu trúc tham số gửi kèm khác nhau tùy theo trường hợp bạn gửi tin nhắn: gửi thường (gửi từng tin lẻ) hoặc gửi batch (gửi hàng loạt).

---

1️⃣ Trường hợp: Gửi thường

Tham số	Ý nghĩa	Kiểu dữ liệu
msg_id	msg_id trả về khi gửi tin qua API	String
status	Trạng thái tin nhắn (success, failed)	String
error_code	Mã lỗi (nếu có)	String / Null

Ví dụ CURL:

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

Ví dụ dữ liệu (dạng JSON để tham khảo cấu trúc):

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

---

2️⃣ Trường hợp: Gửi batch

Tham số	Ý nghĩa	Kiểu dữ liệu
msg_id	msg_id trả về khi gửi tin qua API	String
status	Trạng thái tin nhắn (success, failed)	String
error_code	Mã lỗi (nếu có)	String / Null
phone	Số điện thoại nhận tin (định dạng 84x)	String
tracking_id	Mã theo dõi tin nhắn được gửi kèm trong từng phần tử của mảng data lúc gọi API gửi batch	String

Ví dụ CURL:

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"

Ví dụ dữ liệu (dạng JSON để tham khảo cấu trúc):

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

---

✅ Phản hồi

• HTTP Code: 200 OK
• Webhook trả về HTTP_CODE 200 là thành công
• Danh sách mã lỗi: Tại đây

---

🛡️ Bảo Mật Webhook

• Xác thực IP: Chỉ chấp nhận IP whitelist từ hệ thống chúng tôi.

---

📌 Ghi chú

• Nếu gọi webhook thất bại chúng tôi sẽ gọi lại 2 lần, mỗi lần cách nhau 30s.
• Thời gian webhook phản hồi phải nhỏ hơn 2s. Nếu vượt quá 2s thì xem như thất bại
• tracking_id chỉ xuất hiện ở trường hợp gửi batch, và chính là mã client_message_id mà bạn gửi kèm trong từng tin nhắn khi gọi API gửi tin hàng loạt, dùng để đối soát trạng thái từng tin nhắn cụ thể