ZaloDesk API Zalo cá nhân
Phiên bản v1 · Địa chỉ gốc https://app.zalodesk.com/api/zalo/v1
API này đưa dữ liệu khách hàng từ các tài khoản Zalo cá nhân trong ZaloDesk về CRM, ERP hay website của bạn: hồ sơ khách (số điện thoại, tên gợi nhớ, giới tính, ngày sinh, thẻ, phân loại, ghi chú), hội thoại, tin nhắn kèm nhân viên đã trả lời, nhân viên phụ trách, cuộc gọi Zalo kèm ghi âm và lời thoại, cùng webhook báo theo thời gian thực. API chỉ đọc.
Zalo OA có API riêng: API Zalo OA, dùng chung khoá và webhook với API này.
Cách hoạt động. Dữ liệu Zalo nằm trên máy chủ, tức máy tính của chủ tài khoản đang chạy ZaloDesk. API nhận yêu cầu của bạn, chuyển tới máy chủ, máy chủ đọc dữ liệu rồi trả về. Vì vậy máy chủ cần đang mở. Khi máy chủ tắt, API trả 503 desktop_offline.
1. Khoá API và quyền
Chủ tài khoản tạo khoá trong ZaloDesk trên máy chủ: Cài đặt → API & Webhook → Tạo khoá. Khoá chỉ hiện một lần. Tạo khoá mới thì khoá cũ hết hiệu lực ngay. Mỗi workspace có một khoá, dùng cho cả API Zalo cá nhân và API Zalo OA.
Trên cùng màn hình, chủ tài khoản chọn cho khoá:
- Tài khoản Zalo mà khoá được đọc. Khoá mới chưa có tài khoản nào.
- Quyền của khoá, theo bảng dưới. Khoá mới chưa có quyền nào.
Thay đổi có hiệu lực ngay, không cần tạo lại khoá.
| Quyền | Cho phép đọc | Endpoint · webhook |
|---|---|---|
contacts.read | Hồ sơ khách: tên, tên gợi nhớ, số điện thoại, giới tính, ngày sinh, thẻ, phân loại Zalo, ghi chú. | GET /contacts · GET /contacts/{userId} · GET /tagszalo.contact.* · zalo.friend.requested |
conversations.read | Danh sách hội thoại: tin cuối, số tin chưa đọc, nhân viên phụ trách. | GET /conversations · GET /staff |
messages.read | Nội dung tin nhắn, nhân viên đã gửi, ảnh và tệp trong tin. | GET /messages · GET /search · GET /staffzalo.message.* |
calls.read | Nhật ký cuộc gọi Zalo, ghi âm, lời thoại. | GET /callszalo.call.* |
GET /accounts không cần quyền nào. Ảnh đại diện (avatarUrl) tải được với bất kỳ quyền nào.
Gọi endpoint khi khoá thiếu quyền: 403 {"error":"permission_required","permission":"calls.read"}. Gọi tới tài khoản Zalo không nằm trong khoá: 403 account_forbidden.
2. Xác thực · mã định danh · phân trang · lỗi · giới hạn
Authorization: Bearer zdk.xxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
| Tên | Ý nghĩa |
|---|---|
accountId | Mã Zalo của tài khoản đăng nhập trong ZaloDesk (tài khoản của bạn). Lấy từ GET /accounts. |
userId | Mã Zalo của khách. |
threadId | Mã hội thoại. Chat 1-1: trùng userId của khách. Nhóm: mã nhóm. |
threadType | user (1-1) hoặc group. |
msgId · callId | Mã tin nhắn, mã cuộc gọi. |
staff | Nhân viên ZaloDesk: { "email", "name", "staffKey" }. Xem Nhân viên. |
Mã là chuỗi số, hãy lưu dạng chuỗi (dài hơn số nguyên an toàn của JavaScript). Một khách có thể nhắn nhiều tài khoản Zalo của bạn; hãy ghép khách giữa các tài khoản theo số điện thoại. Thời gian trả về là ISO 8601 UTC; tham số thời gian nhận ISO 8601 hoặc epoch (giây, mili giây).
Phân trang
Các endpoint danh sách nhận limit và cursor, trả nextCursor. Trang sau: gửi lại cursor = nextCursor. Hết dữ liệu: nextCursor là null. cursor là chuỗi mờ, đừng tự tạo.
Lỗi
Dạng chung: {"error":"code","message":"…"}.
| HTTP | error | Nghĩa |
|---|---|---|
| 400 | *_required · *_invalid | Thiếu hoặc sai tham số (ví dụ account_required, cursor_invalid). |
| 401 | unauthorized | Khoá sai hoặc đã bị thay. |
| 403 | permission_required | Khoá thiếu quyền; trường permission cho biết quyền cần có. |
| 403 | account_forbidden | Tài khoản Zalo không nằm trong khoá. |
| 403 | web_access_disabled | Máy chủ đang tắt Cài đặt → Truy cập web. |
| 404 | not_found · contact_not_found · media_not_found | Không có endpoint, khách hoặc tệp đó. |
| 429 | rate_limited | Quá 300 yêu cầu mỗi phút. |
| 503 | desktop_offline | Máy chủ đang tắt hoặc mất mạng. |
| 504 | desktop_timeout | Máy chủ không trả lời trong 25 giây. |
Giới hạn
300 yêu cầu mỗi phút cho mỗi workspace, tính chung với API Zalo OA.
3. Tài khoản
GET/accounts
Các tài khoản Zalo khoá được đọc, quyền của khoá và trạng thái máy chủ. Gọi được cả khi máy chủ tắt.
{ "accounts": [
{ "accountId": "8263541962771234567", "name": "Zalo bán hàng",
"avatarUrl": "https://app.zalodesk.com/api/zalo/v1/media/3f2a9c…" } ],
"permissions": ["contacts.read", "conversations.read", "messages.read", "calls.read"],
"desktop": { "online": true } }
4. Khách hàng · thẻ · phân loại · ghi chú
GET/contacts?accountId=&limit=&cursor=
Quyền contacts.read. Mọi người trong danh bạ, bạn bè và người đã nhắn với tài khoản. limit mặc định 200, tối đa 500.
{ "contacts": [ Contact, … ], "nextCursor": "eyJvIjoyMDB9" }
Đối tượng Contact
| Trường | Nghĩa |
|---|---|
userId | Mã Zalo của khách. |
name | Tên Zalo của khách. |
alias | Tên gợi nhớ tài khoản của bạn đặt cho khách, rỗng khi chưa đặt. |
phone | Số điện thoại, rỗng khi Zalo không cho biết. |
gender | male · female · null. |
birthday | YYYY-MM-DD, --MM-DD khi khách ẩn năm sinh, hoặc null. |
isFriend | Đã kết bạn với tài khoản. |
type | user hoặc group. |
avatarUrl | Ảnh đại diện, null khi máy chủ chưa có ảnh. |
tags | Thẻ gắn cho khách trong ZaloDesk: [{id, name, color}]. |
labels | Phân loại hội thoại của Zalo (đồng bộ với app Zalo): [{id, name, color}]. |
lastMessageAt | Thời điểm tin cuối với khách, null khi chưa nhắn. |
{ "userId": "4821736451230987654", "name": "Nguyễn Văn A", "alias": "Anh A - sỉ Quận 7",
"phone": "0901234567", "gender": "male", "birthday": "1992-05-14", "isFriend": true, "type": "user",
"avatarUrl": "https://app.zalodesk.com/api/zalo/v1/media/9b1e…",
"tags": [ { "id": "12", "name": "Khách sỉ", "color": "#3B82F6" } ],
"labels": [ { "id": "3", "name": "Đã chốt", "color": "#16A34A" } ],
"lastMessageAt": "2026-10-16T02:41:09.000Z" }
GET/contacts/{userId}?accountId=
Quyền contacts.read. Một khách, đủ hồ sơ: mọi trường của Contact, cộng:
| Trường | Nghĩa |
|---|---|
notes | Ghi chú nhân viên viết về khách trong ZaloDesk: [{id, content, createdAt, updatedAt}], mới nhất trước. |
firstMessageAt | Thời điểm tin đầu tiên có trên máy chủ. |
assignees | Nhân viên phụ trách hội thoại với khách: [staff]. Cần thêm quyền conversations.read, nếu không là null. |
{ …Contact,
"notes": [ { "id": "88", "content": "Lấy 50 áo mỗi tháng, giao thứ 6.",
"createdAt": "2026-10-02T03:10:00.000Z", "updatedAt": "2026-10-02T03:10:00.000Z" } ],
"firstMessageAt": "2026-06-11T08:22:40.000Z",
"assignees": [ { "email": "[email protected]", "name": "Lan", "staffKey": "lan01" } ] }
Tìm khách theo số điện thoại: GET /contacts?accountId=&phone=0901234567 trả các khách có số đó.
GET/tags?accountId=
Quyền contacts.read. Mọi thẻ ZaloDesk và phân loại Zalo của tài khoản, để dựng bộ lọc hay ánh xạ sang trường của CRM.
{ "tags": [ { "id": "12", "name": "Khách sỉ", "color": "#3B82F6" } ],
"labels": [ { "id": "3", "name": "Đã chốt", "color": "#16A34A" } ] }
5. Hội thoại · nhân viên phụ trách
GET/conversations?accountId=&since=&limit=&cursor=
Quyền conversations.read. Hội thoại có tin nhắn trên máy chủ, tin mới nhất trước. since (không bắt buộc): chỉ hội thoại có tin sau thời điểm này. limit mặc định 100, tối đa 200.
{ "conversations": [
{ "threadId": "4821736451230987654", "threadType": "user",
"name": "Nguyễn Văn A", "phone": "0901234567", "isFriend": true, "unread": 2,
"avatarUrl": "https://app.zalodesk.com/api/zalo/v1/media/9b1e…",
"assignees": [ { "email": "[email protected]", "name": "Lan", "staffKey": "lan01" } ],
"lastMessage": { "msgId": "7712093388412", "msgType": "webchat", "isSelf": false,
"text": "Còn hàng không shop?", "timestamp": "2026-10-16T02:41:09.000Z" } } ],
"nextCursor": "eyJ0IjoxNzYwNTgyNDY5MDAwfQ" }
assignees: nhân viên ZaloDesk được giao hội thoại này (Phân quyền, Phân luồng). Mảng rỗng khi chưa giao ai; chủ tài khoản luôn thấy mọi hội thoại.
6. Tin nhắn · tìm kiếm
GET/messages?accountId=&threadId=&limit=&cursor=
Quyền messages.read. Tin mới nhất trước. limit mặc định 50, tối đa 100.
{ "messages": [ Message, … ], "nextCursor": "7712093301188" }
Đối tượng Message
| Trường | Nghĩa |
|---|---|
msgId | Mã tin. |
accountId · threadId · threadType | Tài khoản và hội thoại của tin. |
isSelf | true: tài khoản của bạn gửi (từ điện thoại, máy tính hay web ZaloDesk). |
senderId · senderName | Mã Zalo và tên người gửi. senderName có trong nhóm, có thể rỗng. |
staff | Tin của tài khoản do nhân viên gửi qua ZaloDesk: nhân viên đó. null khi chủ tài khoản gửi từ máy chủ hoặc điện thoại, và với tin của khách. |
msgType | webchat (chữ) · chat.photo · share.file · chat.video.msg · chat.voice · chat.sticker · chat.gif · chat.recommended (liên kết, danh thiếp) · chat.location.new · loại khác Zalo thêm sau. |
text | Chữ của tin. Ảnh, tệp, liên kết: tiêu đề hoặc chú thích. null khi không có. |
content | Nội dung gốc Zalo (chuỗi hoặc object). Đường dẫn ảnh, tệp đã được đổi sang đường dẫn ZaloDesk. |
mediaUrls | Đường dẫn tải ảnh, tệp, ghi âm của tin (GET /media/{id}). Mảng rỗng khi máy chủ chưa có tệp. |
quote | Tin được trích dẫn khi đây là tin trả lời: {msgId, senderId, text}, hoặc null. |
recalled | true khi người gửi đã thu hồi tin. |
timestamp | Thời điểm gửi. |
{ "msgId": "7712093391007", "accountId": "8263541962771234567",
"threadId": "4821736451230987654", "threadType": "user",
"isSelf": true, "senderId": "8263541962771234567", "senderName": "",
"staff": { "email": "[email protected]", "name": "Lan", "staffKey": "lan01" },
"msgType": "chat.photo", "text": "Dạ mẫu này còn size M ạ",
"content": { "title": "Dạ mẫu này còn size M ạ", "href": "https://app.zalodesk.com/api/zalo/v1/media/0c77…" },
"mediaUrls": ["https://app.zalodesk.com/api/zalo/v1/media/0c77…"],
"quote": { "msgId": "7712093388412", "senderId": "4821736451230987654", "text": "Còn size M không?" },
"recalled": false, "timestamp": "2026-10-16T02:43:30.000Z" }
GET/search?q=&accountId=
Quyền messages.read. Tìm theo chữ trong tin, q dài 2 đến 120 ký tự. Bỏ accountId để tìm trên mọi tài khoản của khoá. Tối đa 60 kết quả, mới nhất trước.
{ "results": [
{ "accountId": "8263541962771234567", "threadId": "4821736451230987654", "threadType": "user",
"msgId": "7712093388412", "senderId": "4821736451230987654", "msgType": "webchat",
"text": "Còn hàng không shop?", "timestamp": "2026-10-16T02:41:09.000Z" } ] }
7. Cuộc gọi
GET/calls?accountId=&userId=&since=&limit=&cursor=
Quyền calls.read. Cuộc gọi Zalo của tài khoản, mới nhất trước. userId, since không bắt buộc. limit mặc định 50, tối đa 200.
{ "calls": [
{ "callId": "1760583012", "accountId": "8263541962771234567",
"userId": "4821736451230987654", "name": "Nguyễn Văn A",
"direction": "in", "status": "answered",
"startedAt": "2026-10-16T02:50:12.000Z", "endedAt": "2026-10-16T02:54:40.000Z", "durationSeconds": 268,
"recordingUrl": "https://app.zalodesk.com/api/zalo/v1/media/77ad…",
"transcript": [ { "at": 1200, "speaker": "customer", "text": "Shop ơi đơn của anh tới đâu rồi?" },
{ "at": 4800, "speaker": "staff", "text": "Dạ đơn đang giao, chiều nay tới ạ." } ] } ],
"nextCursor": null }
| Trường | Nghĩa |
|---|---|
direction | in (khách gọi tới) · out (gọi cho khách). |
status | answered · missed (không ai nghe) · rejected (bị từ chối) · failed. |
recordingUrl | Ghi âm, null khi cuộc gọi không được ghi âm. |
transcript | Lời thoại: at là mili giây từ đầu cuộc gọi, speaker là customer · staff · ai. null khi chưa có hoặc không chép lời. |
8. Nhân viên
GET/staff
Quyền conversations.read hoặc messages.read. Chủ tài khoản và các chỗ web của nhân viên (Phân quyền), để ghép với người dùng trong CRM. Ghép theo email (email Google nhân viên dùng đăng nhập). staffKey là mã nhân viên của bạn nếu đã đặt (dùng chung với API Zalo OA), null khi chưa đặt.
{ "staff": [
{ "email": "[email protected]", "name": "Chủ shop", "staffKey": null, "kind": "owner", "status": "active" },
{ "email": "[email protected]", "name": "Lan", "staffKey": "lan01", "kind": "web", "status": "active" } ] }
status: active · pending (chưa đăng nhập) · revoked (đã thu hồi; vẫn trả về để tin cũ ghép được).
9. Tải ảnh, tệp, ghi âm
GET/media/{mediaId}
Trả nội dung tệp với Content-Type gốc, hỗ trợ Range. Gửi kèm khoá như mọi yêu cầu khác. Dùng đúng đường dẫn có trong mediaUrls, content, avatarUrl, recordingUrl.
- Ảnh, tệp trong tin cần
messages.read. Ghi âm cầncalls.read. Ảnh đại diện cần một quyền bất kỳ. - Máy chủ cần đang mở để kiểm tra quyền; máy chủ tắt thì trả
503 desktop_offline. Muốn giữ tệp lâu dài, hãy tải về lưu ở hệ thống của bạn.
10. Webhook
Đặt địa chỉ webhook (https) ở Cài đặt → API & Webhook. Địa chỉ và mã bí mật dùng chung với API Zalo OA; sự kiện Zalo cá nhân có type bắt đầu bằng zalo.. Mỗi sự kiện chỉ gửi cho tài khoản nằm trong khoá, khi khoá có quyền ghi ở cột bên phải.
| type | Khi nào · data | Quyền |
|---|---|---|
zalo.message.received | Có tin mới từ người khác, chat 1-1 hoặc nhóm. data: Message. | messages.read |
zalo.message.sent | Tài khoản gửi tin, từ điện thoại, máy tính hay web ZaloDesk. data: Message (có staff). | messages.read |
zalo.contact.created | Khách mới: người lần đầu nhắn tài khoản, hoặc vừa kết bạn. data: Contact. | contacts.read |
zalo.contact.updated | Đổi tên gợi nhớ, số điện thoại, thẻ, phân loại hoặc ghi chú. data: Contact + changed (ví dụ ["tags","notes"]); có notes khi ghi chú đổi. | contacts.read |
zalo.friend.requested | Có người gửi lời mời kết bạn. data: {userId, name, message, avatarUrl}. | contacts.read |
zalo.call.ended | Cuộc gọi kết thúc. data: Call (có thể chưa có transcript). | calls.read |
zalo.call.transcript | Có lời thoại của cuộc gọi. data: Call. | calls.read |
ping | Nút Gửi thử. |
POST https://crm.cua-ban.vn/zalodesk-webhook
Content-Type: application/json
X-ZaloDesk-Event: zalo.message.received
X-ZaloDesk-Delivery: evt_8f2c41d07a93be5512c0e7aa
X-ZaloDesk-Signature: t=1792130469,v1=5d1c…
{ "id": "evt_8f2c41d07a93be5512c0e7aa", "type": "zalo.message.received",
"at": "2026-10-16T02:41:09.000Z",
"accountId": "8263541962771234567", "threadId": "4821736451230987654", "threadType": "user",
"data": { Message } }
- 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. - Sự kiện sinh ra trên máy chủ, nên webhook chạy khi máy chủ đang mở. Việc xảy ra lúc máy chủ tắt được gửi khi máy chủ mở lại và đồng bộ xong. Cần đối chiếu đủ thì dùng các endpoint đọc (xem Đồng bộ vào CRM).
- Lịch sử gửi gần đây (30 lần, mã trạng thái) xem ở Cài đặt → API & Webhook.
Kiểm tra chữ ký (Node.js)
Chữ ký là HMAC-SHA256(mã bí mật, t + "." + body gốc), dạng hex.
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]));
}
// Express: app.post('/zalodesk-webhook', express.raw({ type: 'application/json' }), …)
// kiểm tra chữ ký trên req.body (Buffer) trước khi JSON.parse
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
11. Đồng bộ vào CRM
| CRM | Lấy từ ZaloDesk |
|---|---|
| Khách hàng (contact, lead) | GET /contacts, GET /contacts/{userId}; ghép theo phone, lưu accountId + userId cạnh khách. |
| Trường tuỳ chỉnh, nhóm khách | tags, labels (danh sách đủ ở GET /tags), gender, birthday. |
| Người phụ trách (owner) | assignees của hội thoại; ghép nhân viên theo email (GET /staff). |
| Hoạt động: tin nhắn | GET /messages, webhook zalo.message.*; staff cho biết ai trả lời. |
| Hoạt động: cuộc gọi | GET /calls, webhook zalo.call.*; ghi âm và lời thoại. |
| Ghi chú | notes trong GET /contacts/{userId}, webhook zalo.contact.updated. |
| Lead mới | Webhook zalo.contact.created và zalo.friend.requested. |
Cách làm thường dùng:
- Nhập lần đầu. Với từng tài khoản, lấy hết
GET /contactsvàGET /conversationstheonextCursor. Tạo hoặc cập nhật khách theophone, gán người phụ trách từassignees. - Lịch sử. Với mỗi hội thoại cần lưu, lấy
GET /messagesvàGET /calls?userId=theonextCursortới khi hết. - Theo thời gian thực. Nhận webhook: tạo khách khi có
zalo.contact.created, ghi tin và cuộc gọi vào hoạt động, cập nhật thẻ, ghi chú khi cózalo.contact.updated. - Đối chiếu. Mỗi ngày gọi
GET /conversations?since=vàGET /calls?since=với thời điểm đối chiếu lần trước, lấy bù tin còn thiếu bằngGET /messagestới khi gặpmsgIdđã lưu.
# Tài khoản và quyền của khoá
curl https://app.zalodesk.com/api/zalo/v1/accounts -H "Authorization: Bearer $ZD_KEY"
# Trang đầu danh bạ của một tài khoản
curl "https://app.zalodesk.com/api/zalo/v1/contacts?accountId=8263541962771234567&limit=500" \
-H "Authorization: Bearer $ZD_KEY"
# Hồ sơ đủ của một khách
curl "https://app.zalodesk.com/api/zalo/v1/contacts/4821736451230987654?accountId=8263541962771234567" \
-H "Authorization: Bearer $ZD_KEY"
# Hội thoại có tin mới từ hôm qua
curl "https://app.zalodesk.com/api/zalo/v1/conversations?accountId=8263541962771234567&since=2026-10-15T00:00:00%2B07:00" \
-H "Authorization: Bearer $ZD_KEY"
12. Câu hỏi thường gặp
Máy chủ tắt thì sao?
Các endpoint trừ GET /accounts trả 503 desktop_offline, webhook tạm dừng. Khi máy chủ mở lại, mọi thứ chạy tiếp và webhook gửi những gì đã xảy ra trong lúc tắt.
Lấy được tin cũ đến đâu?
Những tin có trên máy chủ: từ lúc tài khoản đăng nhập ZaloDesk, cộng lịch sử đã đồng bộ vào ZaloDesk.
Tài khoản Zalo trên máy nhân viên có đọc được không?
API đọc tài khoản Zalo đăng nhập trên máy chủ. Tài khoản đăng nhập trên máy nhân viên không nằm trong API này.
API có gửi tin, sửa thẻ hay ghi chú được không?
Không. API này chỉ đọc. Nhân viên làm việc với khách trong ZaloDesk như bình thường; mọi thay đổi về CRM qua webhook.
Thử thế nào?
Tạo khoá, chọn một tài khoản Zalo và quyền, gọi GET /accounts để kiểm tra. Đặt địa chỉ webhook, bấm Gửi thử để kiểm tra chữ ký, rồi nhắn thử một tin vào tài khoản đó.