ZaloDesk API Zalo OA
Phiên bản v1 · Địa chỉ gốc https://app.zalodesk.com/api/oa/hd/v1 · 한국어
API này cho hệ thống của bạn (CRM, website, ứng dụng nội bộ) làm việc với hộp thư Zalo OA trong ZaloDesk: gắn nhân viên, giao khách cho nhân viên, gửi tin dưới tên OA, lấy lịch sử, nhận webhook tin nhắn và cuộc gọi. Tài khoản Zalo cá nhân có API riêng: API Zalo cá nhân, dùng chung khoá và webhook với API này.
1. Xác thực · lỗi · giới hạn
Khoá API tạo trong ZaloDesk trên máy chủ: Zalo OA → API cho hệ thống của bạn. Khoá chỉ hiện một lần. Tạo khoá mới thì khoá cũ bị chặn ngay.
Authorization: Bearer zdk.xxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
- Khách được gọi bằng
zaloUserId= mã người dùng theo OA (sender.id/recipient.idtrong webhook của Zalo), không phải mã theo ứng dụng (user_id_by_app). - Nhân viên được gọi bằng
staffKey, mã nhân viên của bạn (chữ thường, số,-,_, tối đa 64 ký tự). - Khi chỉ kết nối một OA, có thể bỏ
oaId. - Thời gian nhận ISO 8601 (
2026-10-20T14:00:00+07:00) hoặc epoch (giây, mili giây). Trả về ISO UTC. - Lỗi:
{"error":"code","message":"…"}+ HTTP 400 · 401 · 403 · 404 · 409 · 413 · 422 · 429 · 502. - Giới hạn: 300 yêu cầu mỗi phút cho mỗi workspace, tính chung với API Zalo cá nhân. Quá thì trả 429.
2. Nhân viên (staffKey)
Nhân viên là chỗ web hoặc máy nhân viên trong Phân quyền của ZaloDesk. Cả hai được tìm theo email Google (máy nhân viên: email Google đăng nhập trên máy đó). API gắn staffKey của bạn vào chỗ đó và đặt vai trò trên OA. Chỗ web hay máy nhân viên đều giao khách, ghi lịch sử, nhận webhook như nhau.
PUT/staff/{staffKey}
{ "email": "[email protected]", "name": "Minh", "role": "member" }
| Trường | Ý nghĩa |
|---|---|
email | Bắt buộc. Email Google của chỗ web hoặc máy nhân viên trong Phân quyền. Email của chủ tài khoản thì gắn vào chủ. |
role | Không bắt buộc. member (chỉ khách của mình) · lead (khách của các thành viên cùng cấp trên, cộng khách chưa giao). Quản lý (admin, quyền Quản lý của máy nhân viên) chỉ đặt trong ZaloDesk, API không đổi. Bỏ trống thì giữ vai trò cũ. |
oaId | Không bắt buộc. Chỉ đặt vai trò trên OA này. Bỏ trống: mọi OA đã kết nối. |
name | Không bắt buộc. Tên hiển thị. |
seatId | Không bắt buộc. Chọn chỗ nào khi cùng email có cả chỗ web và máy nhân viên (seatId trong GET /staff). |
404 seat_not_found: không có chỗ web hay máy nhân viên với email đó · 409 staff_key_taken: staffKey đã dùng cho chỗ khác · 409 seat_ambiguous: cùng email có cả chỗ web và máy nhân viên, hãy gửi seatId.
GET/staff
{ "staff": [
{ "staffKey": "minh01", "seatId": "72cc…", "kind": "web", "name": "Minh", "email": "[email protected]",
"roles": { "2127279295181006465": "member" }, "status": "accepted" },
{ "staffKey": "hoa01", "seatId": "pc-…", "kind": "pc", "name": "Hoa", "email": "[email protected]",
"roles": { "2127279295181006465": "admin" }, "status": "accepted" } ] }
kind: owner · web (chỗ web) · pc (máy nhân viên). Giá trị roles: admin · lead · member · null (không phụ trách OA này). status: accepted · ready (chưa đăng nhập). Chỗ đã thu hồi, máy đã xoá không có trong danh sách.
3. Giao khách
POST/assign
Ví dụ khi hệ thống của bạn xác nhận khách vừa quét mã QR của một nhân viên. ZaloDesk ghi lịch sử giao (ai, lúc nào, vì sao) và gửi webhook conversation.assigned.
{ "zaloUserId": "3051493754622285408", "staffKey": "minh01",
"reason": "qr", "source": { "qrId": "q-17", "campaign": "thang-10" } }
→ 200 { "oaId": "…", "zaloUserId": "…", "staffKey": "minh01", "seatId": "…",
"assignedAt": "2026-10-15T03:12:00.000Z", "changed": true }
staffKey: null thì bỏ giao. reason là chuỗi tự do (ví dụ qr · marketer · crm), mặc định api. source là object tối đa 1KB, lưu nguyên vào lịch sử. 409 staff_not_on_oa: nhân viên chưa có vai trò trên OA này.
GET/conversations/{zaloUserId}/assignee?at=
Nhân viên phụ trách tại thời điểm đó (ví dụ để tính hoa hồng). Bỏ at = bây giờ.
{ "at": "2026-10-20T07:00:00.000Z",
"assignee": { "staffKey": "minh01", "seatId": "…", "name": "Minh" },
"since": "2026-10-15T03:12:00.000Z" }
GET/conversations/{zaloUserId}/log
Lịch sử giao khách và lịch sử xem (ai đã mở hội thoại). Lịch sử này không xoá được.
POST/staff/{staffKey}/handover
Nhân viên nghỉ việc: chuyển toàn bộ khách người đó phụ trách sang nhân viên khác trong một lần. Khách người nhận đang phụ trách giữ nguyên, khách chuyển sang được cộng thêm. Dùng được cả với chỗ đã thu hồi. Mỗi khách có lịch sử giao và webhook conversation.assigned (reason: "offboarding"). Người nhận chưa có vai trò trên OA đó thì được gắn vai trò member.
{ "to": "lan01" }
→ 200 { "from": "minh01", "to": "lan01", "conversations": 12,
"byOa": { "2127279295181006465": 12 } }
404 staff_not_found: không có staffKey đó · 404 target_not_found: người nhận không tồn tại hoặc đã bị chặn · 400 pc_not_supported: chuyển khách và chặn chỉ dùng cho chỗ web; máy nhân viên xử lý trong Phân quyền của ZaloDesk.
POST/staff/{staffKey}/disable
Chặn chỗ của nhân viên nghỉ việc. Chặn xong, máy tính và điện thoại của người đó bị ngắt ngay và không đăng nhập lại được. Có to thì chuyển hết khách sang người đó trước (như handover) rồi mới chặn; chuyển thất bại thì chỗ không bị chặn. Gọi lại với chỗ đã chặn vẫn được (alreadyDisabled: true). Hội thoại và lịch sử của khách giữ nguyên. Trên máy chủ ZaloDesk làm được y như vậy ở Phân quyền → Thu hồi.
{ "to": "lan01" } // không bắt buộc
→ 200 { "staffKey": "minh01", "disabled": true, "alreadyDisabled": false,
"handover": { "to": "lan01", "conversations": 12, "byOa": { "2127279295181006465": 12 } } }
404 staff_not_found · 404 target_not_found · 400 disable_invalid: tài khoản chủ, hoặc to trùng chính nhân viên đó · 400 pc_not_supported: máy nhân viên (xử lý trong Phân quyền).
4. Gửi tin
POST/messages
{ "zaloUserId": "3051493754622285408", "text": "Chào anh, em là Minh, nhân viên phụ trách của anh." }
{ "zaloUserId": "…", "imageUrl": "https://cua-ban.vn/img/sp-023.jpg", "caption": "Mẫu mới tháng 10\nhttps://cua-ban.vn/sp/023" }
→ 200 { "msgIds": ["c5f1…"] }
- Gửi dưới dạng tin tư vấn của OA, theo đúng quy định của Zalo: trong 48 giờ sau tin cuối của khách thì miễn phí, sau đó tính vào hạn mức tháng của OA, sau 7 ngày Zalo từ chối.
- Ảnh:
imageUrllà https, JPG · PNG tối đa 1MB, GIF tối đa 5MB (giới hạn của Zalo OA). - Tin này về webhook
message.sentvớisender: "api".
5. Thông tin khách · xuất lịch sử · tệp
GET/customers/{zaloUserId}
{ "name": "Anh Minh", "avatar": "https://…", "phone": null,
"lastMessageAt": "…", "lastCustomerAt": "…",
"assignee": { "staffKey": "minh01", "seatId": "…", "name": "Minh" } }
GET/export?from=&to=&cursor=&limit=
Lấy tin đã lưu trong ZaloDesk theo khoảng thời gian (để bù phần thiếu khi máy chủ của bạn ngừng). Gọi mỗi ngày được, gọi lại cùng khoảng nhiều lần cũng được. limit tối đa 500 (mặc định 200). Gọi tiếp bằng cursor tới khi nextCursor là null. Thứ tự: theo khách, trong mỗi khách theo thời gian.
{ "messages": [
{ "zaloUserId": "…", "at": "…", "direction": "out", "msgId": "…", "msgType": "webchat",
"text": "Dạ còn ạ", "fileUrl": null, "sender": "staff", "staffKey": "minh01", "staffName": "Minh" },
{ "zaloUserId": "…", "at": "…", "direction": "in", "msgId": "…", "msgType": "chat.photo",
"text": null, "fileUrl": "https://app.zalodesk.com/api/oa/hd/v1/media/9f…", "customer": { "name": "Anh Minh" } } ],
"nextCursor": "eyJ0Ijo…" }
GET/media/{id}
fileUrl · recordingUrl trong webhook và bản xuất. Tải bằng cùng khoá API. Zalo xoá ảnh, tệp trong chat sau khoảng 14 ngày, nên hãy tải về khi nhận sự kiện.
6. Ghi nhận chia cuộc gọi
Mỗi cuộc gọi vào OA, ZaloDesk lập thứ tự đổ chuông (kế hoạch) và ghi lại đổ chuông ai, lúc nào, ai từ chối, ai nghe máy. Thứ tự: người phụ trách → nhóm của người đó (theo cách của từng nhóm) → nhóm trên → … → chủ tài khoản. Đặt cho từng nhóm hoặc từng người: số giây người phụ trách đổ chuông một mình (ví dụ 20 giây rồi nhóm đổ chuông), và nếu muốn, số cuộc nhỡ liên tiếp (nhỡ N cuộc liên tiếp thì cuộc sau nhóm đổ chuông cùng ngay; người phụ trách nghe máy thì đếm lại từ 0). Số giây nhóm đổ chuông trước khi chuyển lên nhóm trên cũng đặt riêng cho từng nhóm. Khách mới chưa ai phụ trách theo cách “Khách mới gọi đến” của OA. Cài ở ZaloDesk → Phân quyền → Cuộc gọi (bản 0.9.10 trở về trước: Chia khách tự động). Lưu 90 ngày.
GET/calls/routing?oaId=&from=&to=&zaloUserId=&cursor=&limit=
Mới nhất trước. limit tối đa 200 (mặc định 50). Gọi tiếp với cursor tới khi nextCursor là null.
GET/calls/routing/{id}?oaId=
{ "id": "1792054800000.3f9a1c2b7d4e", "oaId": "…", "zaloUserId": "…",
"startedAt": "…", "endedAt": "…",
"outcome": "answered",
"answeredBy": { "staffKey": "hung01", "seatId": "…", "name": "Hùng", "kind": "web" },
"assignee": { "staffKey": "lan01", "seatId": "…", "name": "Lan", "kind": "web" },
"assigneeSource": "assigned",
"steps": [
{ "index": 0, "kind": "assignee", "team": null, "waitSec": 20, "startedAt": "…", "reason": "start" },
{ "index": 1, "kind": "team", "team": { "staffKey": "minh01", "seatId": "…", "name": "Minh", "kind": "pc" },
"waitSec": 20, "startedAt": "…", "reason": "timer" } ],
"people": [
{ "staffKey": "lan01", "seatId": "…", "name": "Lan", "kind": "web", "step": 0, "status": "taken_by_other", "rangAt": "…", "until": "…" },
{ "staffKey": "minh01", "seatId": "…", "name": "Minh", "kind": "pc", "step": 1, "status": "declined", "rangAt": "…", "until": "…" },
{ "staffKey": "hung01", "seatId": "…", "name": "Hùng", "kind": "web", "step": 1, "status": "answered", "rangAt": "…", "until": "…" },
{ "staffKey": "tu01", "seatId": "…", "name": "Tú", "kind": "web", "step": 1, "status": "offline", "rangAt": null, "until": null, "notifiedAt": "…" } ],
"deviations": [] }
| Trường | Giá trị |
|---|---|
outcome | answered có người nghe · missed gọi nhỡ · declined mọi người từ chối · ringing đang đổ chuông |
assigneeSource | assigned đã giao từ trước · rotation giao lần lượt khi gọi · fixed người cố định · answer người nghe máy · missed gọi nhỡ, giao lần lượt · none chưa ai phụ trách |
steps[].kind | assignee người phụ trách · team nhóm (team = trưởng nhóm) · owner nhóm của chủ tài khoản · new khách mới chưa ai phụ trách · all OA không chia việc |
steps[].misses | Chỉ khi bật số cuộc nhỡ liên tiếp: { "limit": N, "streak": số cuộc nhỡ liên tiếp trước cuộc này }. streak < limit: người phụ trách đổ chuông một mình số giây đã đặt (waitSec), ngược lại nhóm đổ chuông cùng lúc (waitSec 0). Còn lại null |
steps[].reason | Vì sao bước bắt đầu: start · timer (bước trước đã đổ chuông waitSec giây) · empty (bước trước không có ai để đổ chuông) · nobody (người ở bước trước đều từ chối hoặc mất kết nối). Bước chưa tới là null |
people[].status | answered nghe máy · taken_by_other đổ chuông, người khác đã nghe · no_answer đổ chuông, không nghe · declined từ chối · left mất kết nối khi đang đổ chuông · no_permission chưa có quyền gọi OA này, bỏ qua, không báo · offline không mở ZaloDesk, bỏ qua · not_reached cuộc gọi kết thúc trước lượt · pending đang gọi · not_rung lẽ ra phải đổ chuông mà không (lỗi của ZaloDesk) |
people[].notifiedAt | Lúc gửi thông báo cuộc gọi (push) cho người bị bỏ qua vì không mở ZaloDesk; null nếu không gửi. Mở ZaloDesk từ thông báo khi cuộc gọi còn đổ chuông thì người đó cũng đổ chuông và nghe được |
deviations | Chỗ đổ chuông khác kế hoạch. Có nội dung thì ZaloDesk đã tự nhận lỗi để sửa. |
7. Webhook
Địa chỉ webhook (https) đặt ở cùng màn hình trên máy chủ ZaloDesk. Khoá ký (whsec_…) khác với khoá thẻ khách hàng và khoá API.
POST {địa chỉ của bạn}
Content-Type: application/json
X-ZaloDesk-Event: message.sent
X-ZaloDesk-Delivery: evt_3caa071d9727f28494f61dfa
X-ZaloDesk-Signature: t=1791989815,v1=5d1c…
{ "id": "evt_3caa071d9727f28494f61dfa", "type": "message.sent", "at": "2026-10-15T03:12:05.000Z",
"oaId": "2127279295181006465", "zaloUserId": "3051493754622285408", "data": { … } }
- Trả 2xx trong 10 giây là thành công. Nếu không, ZaloDesk gửi lại sau 30 giây, 1 phút, 2 phút… tối đa cách 1 giờ, trong 24 giờ.
- Một sự kiện gửi lại vẫn giữ
idcũ. Bỏ quaidđã nhận. - Không bảo đảm thứ tự. Sắp theo
at. - Lịch sử gửi (30 lần gần nhất, mã trạng thái) xem ở mục Lần gửi gần đây trên màn hình quản lý. Bấm Gửi thử hoặc gọi
POST /webhook/testđể gửi sự kiệnping.
Kiểm tra chữ ký (PHP)
$raw = file_get_contents('php://input');
preg_match('/t=(\d+),v1=([a-f0-9]+)/', $_SERVER['HTTP_X_ZALODESK_SIGNATURE'] ?? '', $m);
$ok = $m && abs(time() - (int)$m[1]) < 300
&& hash_equals(hash_hmac('sha256', $m[1] . '.' . $raw, ZD_WEBHOOK_SECRET), $m[2]);
if (!$ok) { http_response_code(401); exit; }
$event = json_decode($raw, true);
// kiểm tra $event['id'] đã nhận chưa → lưu → 200
Kiểm tra chữ ký (Node.js)
const crypto = require('crypto');
function verifyZaloDesk(rawBody, header, secret) {
const m = /t=(\d+),v1=([a-f0-9]+)/.exec(header || '');
if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false;
const expected = crypto.createHmac('sha256', secret).update(`${m[1]}.${rawBody}`).digest('hex');
return expected.length === m[2].length
&& crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]));
}
Sự kiện
| type | data |
|---|---|
message.received | msgId (mã tin Zalo) · msgType · text · fileUrl · title · customer: {name, avatar} |
message.sent | msgId · msgType · text · fileUrl · sender · staffKey · staffNamesender: staff (nhân viên gửi trong ZaloDesk) · auto (trả lời tự động, lời chào) · api (máy chủ của bạn gửi qua /messages) · ai (AI trả lời, dự kiến) · external (gửi ngoài ZaloDesk, ví dụ OA Manager hoặc ứng dụng của bạn) |
conversation.assigned | from · to · by (mỗi trường là {staffKey, seatId} hoặc null; by có thể là "api") · reason · source |
conversation.viewed | staffKey · seatId (cùng nhân viên, cùng hội thoại: 5 phút một lần) |
call.ended | callId · direction (in/out) · startedAt · talkSeconds · missed · video (Zalo báo cuộc gọi kết thúc) |
call.recorded | callId · direction · startedAt · endedAt · durationSeconds · staffKey (nhân viên nghe hoặc gọi) · staffName · recordingUrl · transcript (pending/none) |
call.transcript | callId · lines: [{at(ms), s("c" khách | "s" nhân viên), x(câu)}] |
call.routed | Khi một cuộc gọi vào OA kết thúc: cùng nội dung với GET /calls/routing/{id} (đổ chuông ai, lúc nào, ai nghe máy) |
customer.followed · customer.unfollowed | (không có) |
customer.updated | name · phone (khi khách gửi biểu mẫu thông tin) |
ping | message (gửi thử) |
Cùng một cuộc gọi, call.ended và call.recorded có thể có callId khác nhau (mã của Zalo và mã của tổng đài). Ghép theo zaloUserId và thời gian.
8. Thẻ khách hàng
Trang của bạn hiện trong ZaloDesk, cạnh hội thoại OA (cài ở Cài đặt → Zalo OA → Thẻ khách hàng).
- ZaloDesk mở trang thẻ với
?oaId=&zaloUserId=&token=.zaloUserIdlà mã theo OA. - token: JWT HS256 (ký bằng khoá thẻ), hạn 10 phút.
{ iss:"zalodesk", aud:<origin của trang>, oaId, zaloUserId, staff:{ id, key, email, name, role }, assigneeId, iat, exp }.staff.key= staffKey của nhân viên đó. - Chuyển sang hội thoại khác thì trang được mở lại với khách mới.
- Token mới: ZaloDesk gửi
{type:"zalodesk.token", token, expiresAt}mỗi 8 phút. Trang gửi{type:"zalodesk.token.request"}thì ZaloDesk gửi ngay. - Sự kiện:
{type:"zalodesk.event", event:"message.received" | "message.sent" | "assignee.changed", oaId, zaloUserId, at}. - ZaloDesk không lưu thông tin hiển thị trên thẻ.
9. Câu hỏi thường gặp
Tin ZaloDesk gửi dưới tên OA có về webhook ứng dụng Zalo của bạn (oa_send_text…) không?
Có. Ứng dụng Zalo kết nối cùng OA nhận mọi tin OA gửi, dù gửi từ công cụ nào (tin ứng dụng của bạn gửi cũng vào ZaloDesk như vậy). msg_id của tin đó trùng msgId trong webhook message.sent, nên ghép theo mã tin để biết nhân viên đã gửi (staffKey).
Thử thế nào?
Thử với OA thật. Tạo khoá, đặt địa chỉ webhook, bấm Gửi thử để kiểm tra chữ ký, rồi gắn một nhân viên bằng PUT /staff và /assign thử một hội thoại khách.