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
  2. Xác thực · mã định danh · phân trang · lỗi · giới hạn
  3. Tài khoản
  4. Khách hàng · thẻ · phân loại · ghi chú
  5. Hội thoại · nhân viên phụ trách
  6. Tin nhắn · tìm kiếm
  7. Cuộc gọi
  8. Nhân viên
  9. Tải ảnh, tệp, ghi âm
  10. Webhook
  11. Đồng bộ vào CRM
  12. Câu hỏi thường gặp

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á:

Thay đổi có hiệu lực ngay, không cần tạo lại khoá.

QuyềnCho phép đọcEndpoint · webhook
contacts.readHồ 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 /tags
zalo.contact.* · zalo.friend.requested
conversations.readDanh 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.readNội dung tin nhắn, nhân viên đã gửi, ảnh và tệp trong tin.GET /messages · GET /search · GET /staff
zalo.message.*
calls.readNhật ký cuộc gọi Zalo, ghi âm, lời thoại.GET /calls
zalo.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
accountIdMã 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.
userIdMã Zalo của khách.
threadIdMã hội thoại. Chat 1-1: trùng userId của khách. Nhóm: mã nhóm.
threadTypeuser (1-1) hoặc group.
msgId · callIdMã tin nhắn, mã cuộc gọi.
staffNhâ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":"…"}.

HTTPerrorNghĩa
400*_required · *_invalidThiếu hoặc sai tham số (ví dụ account_required, cursor_invalid).
401unauthorizedKhoá sai hoặc đã bị thay.
403permission_requiredKhoá thiếu quyền; trường permission cho biết quyền cần có.
403account_forbiddenTài khoản Zalo không nằm trong khoá.
403web_access_disabledMáy chủ đang tắt Cài đặt → Truy cập web.
404not_found · contact_not_found · media_not_foundKhông có endpoint, khách hoặc tệp đó.
429rate_limitedQuá 300 yêu cầu mỗi phút.
503desktop_offlineMáy chủ đang tắt hoặc mất mạng.
504desktop_timeoutMá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ườngNghĩa
userIdMã Zalo của khách.
nameTên Zalo của khách.
aliasTên gợi nhớ tài khoản của bạn đặt cho khách, rỗng khi chưa đặt.
phoneSố điện thoại, rỗng khi Zalo không cho biết.
gendermale · female · null.
birthdayYYYY-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.
typeuser hoặc group.
avatarUrlẢnh đại diện, null khi máy chủ chưa có ảnh.
tagsThẻ gắn cho khách trong ZaloDesk: [{id, name, color}].
labelsPhân loại hội thoại của Zalo (đồng bộ với app Zalo): [{id, name, color}].
lastMessageAtThờ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ườngNghĩa
notesGhi chú nhân viên viết về khách trong ZaloDesk: [{id, content, createdAt, updatedAt}], mới nhất trước.
firstMessageAtThời điểm tin đầu tiên có trên máy chủ.
assigneesNhâ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ườngNghĩa
msgIdMã tin.
accountId · threadId · threadTypeTài khoản và hội thoại của tin.
isSelftrue: tài khoản của bạn gửi (từ điện thoại, máy tính hay web ZaloDesk).
senderId · senderNameMã Zalo và tên người gửi. senderName có trong nhóm, có thể rỗng.
staffTin 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.
msgTypewebchat (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.
textChữ của tin. Ảnh, tệp, liên kết: tiêu đề hoặc chú thích. null khi không có.
contentNộ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.
quoteTin được trích dẫn khi đây là tin trả lời: {msgId, senderId, text}, hoặc null.
recalledtrue khi người gửi đã thu hồi tin.
timestampThờ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ườngNghĩa
directionin (khách gọi tới) · out (gọi cho khách).
statusanswered · missed (không ai nghe) · rejected (bị từ chối) · failed.
recordingUrlGhi âm, null khi cuộc gọi không được ghi âm.
transcriptLờ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.

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.

typeKhi nào · dataQuyền
zalo.message.receivedCó tin mới từ người khác, chat 1-1 hoặc nhóm. data: Message.messages.read
zalo.message.sentTà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.createdKhá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.requestedCó người gửi lời mời kết bạn. data: {userId, name, message, avatarUrl}.contacts.read
zalo.call.endedCuộc gọi kết thúc. data: Call (có thể chưa có transcript).calls.read
zalo.call.transcriptCó lời thoại của cuộc gọi. data: Call.calls.read
pingNú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 } }

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

CRMLấ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áchtags, 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ắnGET /messages, webhook zalo.message.*; staff cho biết ai trả lời.
Hoạt động: cuộc gọiGET /calls, webhook zalo.call.*; ghi âm và lời thoại.
Ghi chúnotes trong GET /contacts/{userId}, webhook zalo.contact.updated.
Lead mớiWebhook zalo.contact.created và zalo.friend.requested.

Cách làm thường dùng:

  1. Nhập lần đầu. Với từng tài khoản, lấy hết GET /contacts và GET /conversations theo nextCursor. Tạo hoặc cập nhật khách theo phone, gán người phụ trách từ assignees.
  2. Lịch sử. Với mỗi hội thoại cần lưu, lấy GET /messages và GET /calls?userId= theo nextCursor tới khi hết.
  3. 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.
  4. Đố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ằng GET /messages tới khi gặp msgId đã 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 đó.