Gửi tin
POST /v1/messages: gửi một tin theo mẫu đã duyệt. Địa chỉ gốc: https://app.zapro.vn/v1.
POST/v1/messages Gửi một tin. Trả 202 kèm tin vừa tạo.
| Trường | Bắt buộc | Ý nghĩa |
|---|---|---|
| oa | Có | Mã OA (xem trang Zalo OA) hoặc "sandbox" để gửi thử. |
| to | Có | Số điện thoại người nhận: 0901234567 hoặc 84901234567. |
| template | Có | Mã mẫu hoặc mã mẫu của Zalo. |
| data | Theo mẫu | Giá trị cho từng tham số của mẫu. ZaPro kiểm tra thiếu, thừa và độ dài trước khi gửi. |
| tracking_id | Không | Mã đơn hoặc lịch hẹn bên hệ thống của bạn, tối đa 120 ký tự. |
| scheduled_at | Không | Hẹn giờ gửi, ISO 8601, ví dụ 2026-11-08T09:00:00+07:00, trong vòng 30 ngày. Tên cũ send_at vẫn nhận. |
curl -X POST https://app.zapro.vn/v1/messages \ -H "Authorization: Bearer $ZAPRO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "oa": "hoa-sen-spa", "to": "0901234567", "template": "xac-nhan-lich-hen", "data": { "ten": "Lan", "dich_vu": "Gội đầu dưỡng sinh", "gio": "15:30", "ngay": "08/11" } }'
const res = await fetch("https://app.zapro.vn/v1/messages", { method: "POST", headers: { Authorization: `Bearer ${process.env.ZAPRO_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ oa: "hoa-sen-spa", to: "0901234567", template: "xac-nhan-lich-hen", data: { "ten": "Lan", "dich_vu": "Gội đầu dưỡng sinh", "gio": "15:30", "ngay": "08/11" }, }), }); const message = await res.json();
$ch = curl_init("https://app.zapro.vn/v1/messages"); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("ZAPRO_API_KEY"), "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode([ "oa" => "hoa-sen-spa", "to" => "0901234567", "template" => "xac-nhan-lich-hen", "data" => ["ten" => "Lan", "dich_vu" => "Gội đầu dưỡng sinh", "gio" => "15:30", "ngay" => "08/11"], ]), ]); $message = json_decode(curl_exec($ch), true);
import os, requests res = requests.post( "https://app.zapro.vn/v1/messages", headers={"Authorization": f"Bearer {os.environ['ZAPRO_API_KEY']}"}, json={ "oa": "hoa-sen-spa", "to": "0901234567", "template": "xac-nhan-lich-hen", "data": { "ten": "Lan", "dich_vu": "Gội đầu dưỡng sinh", "gio": "15:30", "ngay": "08/11" }, }, ) message = res.json()
Phản hồi 202
{
"object": "message",
"id": "msg_01jd9a7f…",
"status": "queued",
"oa": "hoa-sen-spa",
"to": "0901234567",
"template": "xac-nhan-lich-hen",
"scheduled_at": null,
"held_reason": null,
"error": null
}Trạng thái tin
queued → sending → sent → delivered. Ngoài ra: scheduled (hẹn giờ, hoặc đang được giữ vì ngoài khung giờ), failed, canceled.
Chống gửi trùng
Gửi header Idempotency-Key (tối đa 200 ký tự). Gửi lại cùng khóa chỉ tạo một tin và trả về đúng tin đó, kể cả khi lần đầu bị mất kết nối.
Khung giờ 07:00–22:00
Tin giao dịch đi ngay lúc nào cũng được. Tin chăm sóc và quảng cáo rơi ngoài 07:00–22:00 được trả về với status: "scheduled" và held_reason, rồi tự gửi lúc 07:00.
Gửi hàng loạt
POST/v1/messages/batch Body là mảng tối đa 100 tin, hoặc { "messages": [...] }. Trả 207 kèm kết quả từng tin theo thứ tự: mã tin, hoặc lỗi của riêng tin đó.