Tài liệu cho đội kỹ thuật của doanh nghiệp. API cho phép CRM của bạn đọc và gửi tin qua cả nick Zalo cá nhân lẫn Zalo Official Account (OA) đã kết nối trên ZaChat trong cùng một chuẩn dữ liệu; webhook đẩy tin mới về CRM theo thời gian thực.
- Base URL:
https://api.zachat.vn/api/v1 - Định dạng: JSON (UTF-8), trường
snake_case, thời gian là Unix mili giây. - Kết nối nick Zalo (quét QR cho nick cá nhân, cấp quyền OAuth cho Zalo OA) làm trên ZaChat (web / máy tính). API không quét QR hay nối OA mới.
- Đặc tả OpenAPI 3.1: xem tương tác (Swagger) ·
tải
zachat-api-v1.yaml— import vào Postman hoặc sinh SDK.
Cách lấy API key và cài webhook#
Chủ tổ chức (gói Doanh nghiệp trở lên) tự tạo trong ZaChat, không cần liên hệ ai:
- Mở ZaChat (web hoặc ứng dụng máy tính) → Cài đặt → API & Webhook.
- API key: bấm Tạo API key, chọn quyền và nick được dùng, sao chép key (chỉ hiện một lần). Mỗi tổ chức có một key; Đổi key sẽ thu hồi key cũ ngay.
- Webhook: nhập URL
https://…của CRM, chọn sự kiện và nick, sao chép secret (chỉ hiện một lần). Bấm Gửi thử để kiểm tra, Lần gửi gần đây để xem lỗi nếu CRM trả mã khác 2xx.
Đang dùng thử hoặc chưa có gói Doanh nghiệp? Đăng ký tích hợp, ZaChat sẽ cấp key giúp bạn. Doanh nghiệp không có lập trình viên riêng được đội kỹ thuật ZaChat hỗ trợ tích hợp miễn phí.
1. Xác thực#
API key (dạng zk_live_…) — giữ bí mật, chỉ dùng phía server của CRM. Gửi kèm mọi request:
Authorization: Bearer zk_live_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Mỗi key có:
- Quyền:
messages:read(đọc hội thoại Zalo & Kênh chung),messages:send(gửi, sửa, thu hồi, cảm xúc, ghim, đánh dấu đã đọc, kết bạn),team:read(xem nhân viên). - Phạm vi nick: mọi nick của tổ chức, hoặc một số nick nhất định (Kênh chung là kênh nội bộ chung của tổ chức, không phụ thuộc phạm vi nick Zalo).
Phân quyền nhân viên nào được xem / nhắn hội thoại nào do CRM của bạn quyết định.
Hội thoại mà người quét nick để ở chế độ riêng tư trên ZaChat không truy cập được qua API và không có trong webhook.
2. Người thao tác (user_id)#
Mọi lệnh ghi (gửi, chuyển tiếp…) nhận user_id (tuỳ chọn) — id thành viên ZaChat của nhân viên đang thao tác, lấy từ
GET /team. ZaChat ghi nhận tin do người này gửi (hiện đúng tên trên app ZaChat, tính vào báo cáo theo nhân viên).
- Không truyền → ghi theo chủ tổ chức.
user_idkhông phải thành viên đang hoạt động → lỗi422 INVALID_USER_ID.- Nhân viên cần có tài khoản thành viên trên ZaChat để được ghi nhận đúng tên.
3. Lỗi#
{ "error": { "code": "ACCOUNT_OFFLINE", "message": "Nick Zalo đang ngắt kết nối. Vui lòng kết nối lại trên ZaChat." } }
| HTTP | code | Ý nghĩa |
|---|---|---|
| 400 | VALIDATION_ERROR | Thiếu / sai tham số (vd. chữ Zalo OA > 2.000 ký tự, album OA > 10 ảnh) |
| 401 | UNAUTHORIZED | Key sai hoặc đã thu hồi |
| 402 | PLAN_EXPIRED | Gói ZaChat của tổ chức hết hạn |
| 402 | PLAN_NOT_INCLUDED | Gói hiện tại không bao gồm API (vd. đã hạ xuống gói thấp hơn) |
| 403 | FORBIDDEN_SCOPE | Key không có quyền này |
| 403 | ORG_SUSPENDED | Tổ chức bị khoá |
| 404 | ACCOUNT_NOT_FOUND | Nick không tồn tại / ngoài phạm vi key |
| 404 | THREAD_NOT_VISIBLE | Hội thoại không tồn tại hoặc riêng tư |
| 404 | MESSAGE_NOT_FOUND, MEDIA_NOT_FOUND, USER_NOT_FOUND | Không tìm thấy |
| 409 | ACCOUNT_OFFLINE | Nick đang mất kết nối Zalo (hoặc Zalo OA bị gỡ quyền) |
| 422 | INVALID_USER_ID | user_id không phải thành viên đang hoạt động |
| 422 | NOT_SUPPORTED | Thao tác không có trong capabilities của nick (vd. thu hồi / ghim / sticker / tra SĐT trên Zalo OA) — ẩn nút, không thử lại |
| 422 | REPLY_WINDOW_EXPIRED | Zalo OA đã quá 7 ngày kể từ lần cuối khách tương tác (details.expires_at) — chờ khách nhắn lại |
| 422 | OA_PACKAGE_REQUIRED | Zalo trả -224: Zalo OA đang ở gói miễn phí, chủ OA cần nâng gói trên zalo.cloud |
| 422 | MEDIA_NOT_ALLOWED | Tệp không đúng loại / vượt kích thước kênh cho phép (OA chỉ nhận PDF/DOC/DOCX/CSV ≤ 5MB, ảnh nén ≤ 1MB) |
| 429 | RATE_LIMITED | Gọi quá nhanh — thử lại sau |
| 429 | QUOTA_EXCEEDED | Hết hạn mức kết bạn trong ngày |
| 502 | ZALO_ERROR | Zalo từ chối / lỗi khi gọi Zalo |
| 503 | SERVICE_RESTARTING | ZaChat đang cập nhật hoặc nick đang kết nối lại sau khi cập nhật — thử lại sau số giây trong header Retry-After |
| 500 | INTERNAL_ERROR | Lỗi hệ thống ZaChat |
Giới hạn tốc độ: 600 request / phút mỗi key; 30 lệnh gửi / phút mỗi nick; 30 lần tra SĐT / giờ mỗi nick. Gửi quá nhiều, quá nhanh từ nick Zalo cá nhân có thể khiến Zalo khoá nick — hãy nhắn như người thật.
4. Nick & nhân viên#
GET /accounts#
{ "data": [
{
"id": "acc_123456789", "zalo_id": "123456789", "name": "CSKH 1", "avatar": "https://…",
"channel": "zalo_personal",
"capabilities": ["send_text","send_image","send_file","send_video","send_voice","sticker","location","album",
"quote","mentions","recall","reactions","pin","forward","lookup_phone","friend_requests"],
"is_online": true
},
{
"id": "acc_388613280878808645", "zalo_id": "388613280878808645", "name": "Shop ABC Official", "avatar": "https://…",
"channel": "zalo_oa",
"capabilities": ["send_text","send_image","send_file","album","quote","reply_window"],
"is_online": true
}
] }
channel:"zalo_personal"hoặc"zalo_oa"(CRM cũ nếu gặp bản lưu thiếuchannelthì hiểu là"zalo_personal").capabilities: danh sách thao tác loại nick đó hỗ trợ (luôn trả đủ ngay cả khiis_online: false). CRM dùng mảng này để ẩn / hiện nút và bỏ qua tên lạ (sau này ZaChat có thể thêm tên mới mà không làm vỡ CRM). Xem chi tiết ở mục 8d. Zalo OA.
GET /team (quyền team:read)#
{ "data": [
{ "user_id": "8f0c…", "name": "Nguyễn An", "email": "an@cty.vn", "role": "OWNER", "status": "active", "assigned_account_ids": ["*"] },
{ "user_id": "b21e…", "name": "Trần Bình", "email": "binh@cty.vn", "role": "STAFF", "status": "active", "assigned_account_ids": ["acc_123456789"] }
] }
assigned_account_ids chỉ để tham khảo (phân công trên app ZaChat) — API không dùng để chặn.
5. Hội thoại & tin nhắn#
thread_id: id người dùng Zalo (chat 1-1) hoặc id nhóm. Khi gọi API có thể thêm tiền tố u (người) / g (nhóm) để
chỉ rõ loại hội thoại, ví dụ g7712… — nên dùng tiền tố khi gửi vào nhóm.
GET /accounts/{account_id}/threads?limit=50&cursor=#
Danh sách để đồng bộ hội thoại về CRM, xếp theo thời điểm cập nhật cũ → mới:
- Lần đầu: gọi không có
cursor, rồi gọi tiếp vớicursor = next_cursorcho tới khinext_cursorlànull. Một trang có thể ít hơnlimit, kể cả rỗng (hội thoại riêng tư bị lọc) — chỉ dừng khinext_cursor = null. - Lưu
sync_cursorcủa trang cuối. Lần đồng bộ sau gọi vớicursor = sync_cursorđể chỉ lấy hội thoại có thay đổi (tin mới, đổi tên, đã đọc…) — có thể nhận lại vài hội thoại đã có, hãy upsert theoid.
Hiển thị "mới nhất lên đầu" thì CRM sắp xếp theo last_message_at trong dữ liệu đã đồng bộ.
{
"data": [ {
"id": "987654321", "account_id": "acc_123456789", "channel": "zalo_personal", "name": "Khách A", "avatar": null, "is_group": false,
"unread_count": 2, "last_message_preview": "Còn hàng không shop?", "last_message_at": 1762934400000,
"last_message_is_outgoing": false, "is_pinned": false, "labels": []
} ],
"next_cursor": "…", "sync_cursor": "…"
}
GET /accounts/{account_id}/threads/{thread_id}/messages?limit=50&before=#
Trang tin mới nhất, xếp cũ → mới. Lấy tin cũ hơn: truyền next_before của trang trước (null = hết).
Lịch sử có từ lúc nick kết nối ZaChat trở đi — Zalo không cho tải lại tin 1-1 cũ hơn thời điểm đó (nhóm có thể có thêm một ít tin cũ).
GET /accounts/{account_id}/messages/{msg_id}#
Đối tượng tin nhắn#
{
"id": "7234567890123",
"account_id": "acc_123456789",
"channel": "zalo_personal", // "zalo_personal" | "zalo_oa"
"thread_id": "987654321",
"is_group": false,
"direction": "in", // in = khách gửi, out = nick gửi
"sender": { "zalo_id": "987654321", "name": "Khách A" },
"user_id": null, // nhân viên ZaChat đã gửi (tin out từ app / API)
"source": null, // "api" (gửi qua API) | "oa_manager" (admin gửi từ oa.zalo.me) | null
"idempotency_key": null, // key của lệnh gửi qua API (để khớp kết quả); null với tin khác
"type": "photo", // text | photo | video | voice | file | sticker | link | location | contact_card | bank_card | call | system | recalled | other
"text": "Mẫu này còn size M không?", // nội dung chữ hoặc chú thích
"media": { "url": "https://…", "thumbnail_url": "https://…", "file_name": null, "file_size": null, "mime_type": null, "width": 1080, "height": 1440, "duration_seconds": null },
"sticker": null,
"location": null,
"quote": { "msg_id": "7234567890000", "sender_id": "123456789", "sender_name": "Bạn", "text": "Shop gửi mẫu ạ" },
"mentions": [],
"reactions": { "❤️": 1 },
"is_recalled": false,
"is_pinned": false,
"timestamp": 1762934400000,
"raw_content": "{…}" // nội dung gốc từ Zalo, cho trường chưa có trong schema
}
Link media từ Zalo có thời hạn — nếu cần lưu lâu dài, CRM nên tải file về lưu.
6. Gửi tin#
Mọi lệnh gửi bắt buộc idempotency_key (1–100 ký tự A-Z a-z 0-9 . _ : -), duy nhất cho mỗi tin của bạn. Gửi lại cùng
key (vd. mạng lỗi, không biết đã gửi chưa) → ZaChat không gửi lần 2, trả lại kết quả cũ.
Kết quả:
201 { "status": "sent", "message": {…}, "messages": [ … ] }— đã gửi.200— cùngidempotency_keyđã gửi trước đó (trả lại kết quả cũ).202 { "status": "pending" }— Zalo phản hồi chậm (> 25 giây); tin vẫn đang gửi. Kết quả cuối đến qua webhookmessage.senthoặcmessage.failed, cả hai đều kèmidempotency_keycủa lệnh. Đừng gửi lại bằng key mới.
Gửi lại an toàn#
ZaChat nhớ mỗi idempotency_key 24 giờ, nên CRM có thể gửi lại thoải mái mà khách không nhận tin trùng:
| CRM nhận được | Nên làm |
|---|---|
201 / 200 | Đã gửi xong — lưu message.id |
202 pending | Chờ webhook message.sent / message.failed có cùng idempotency_key; quá 15 phút chưa có thì gửi lại cùng key |
Lỗi mạng, hết thời gian chờ, 502 / 503 / 500 | Không biết đã gửi chưa → gửi lại cùng key, giãn dần (5 giây, 30 giây, 2 phút, 10 phút…) |
429, 503 SERVICE_RESTARTING | Chờ theo header Retry-After rồi gửi lại cùng key |
409 ACCOUNT_OFFLINE | Báo nhân viên quét lại nick; gửi lại cùng key khi nick online |
4xx khác | Lỗi dữ liệu — không gửi lại, báo cho người dùng |
Nên lưu tin cần gửi vào hàng đợi phía CRM và hiện trạng thái "Đang gửi" cho tới khi có 201 / 200 hoặc webhook xác
nhận. Nếu ZaChat gặp sự cố đúng lúc đang gửi, trạng thái "đang gửi" của key được giữ 15 phút: gửi lại trong thời gian này
nhận 202, không gửi trùng.
POST /accounts/{account_id}/threads/{thread_id}/messages#
Chữ:
{ "idempotency_key": "crm-msg-8812", "type": "text", "text": "Dạ shop chào anh ạ", "user_id": "b21e…" }
Trả lời trích dẫn: thêm "quote_msg_id": "7234567890000" (tin trong cùng hội thoại).
Nhắc tên trong nhóm (offset, length tính theo ký tự trong text; user_id "-1" = @Tất cả):
{ "idempotency_key": "k1", "type": "text", "text": "@Bình xử lý đơn này nhé",
"mentions": [ { "user_id": "112233", "offset": 0, "length": 5 } ] }
Ảnh / video / ghi âm / tệp — tải lên trước bằng POST /media, rồi gửi media_id:
{ "idempotency_key": "k2", "type": "photo", "media_id": "med_3f9a…", "text": "Mẫu mới về" }
type: photo | video | voice | file (text là chú thích, bỏ qua với voice / file).
Sticker: { "type": "sticker", "sticker": { "id": 21455, "category_id": 10302, "type": 7 } }
(lấy nguyên id, category_id, type từ sticker của một tin sticker đã nhận; thiếu type thì mặc định 7).
Vị trí: { "type": "location", "location": { "latitude": 10.7769, "longitude": 106.7009, "title": "Cửa hàng Q1", "address": "…" } }
POST /media (multipart/form-data, field file, tối đa 50MB)#
curl -X POST https://api.zachat.vn/api/v1/media \
-H "Authorization: Bearer $ZACHAT_KEY" -F "file=@/path/anh.jpg"
{ "media_id": "med_3f9a…", "url": "https://…", "file_name": "anh.jpg", "mime_type": "image/jpeg", "file_size": 183021,
"width": 1080, "height": 1440, "expires_in_seconds": 86400 }
media_id dùng được trong 24 giờ, cho mọi nick của tổ chức.
POST /accounts/{account_id}/threads/{thread_id}/albums — nhiều ảnh thành một album#
{ "idempotency_key": "k3", "media_ids": ["med_a…", "med_b…", "med_c…"], "user_id": "b21e…" }
- Nick cá nhân: 2–20 ảnh (gộp thành 1 album trên Zalo).
- Zalo OA: 2–10 ảnh (Zalo OA không có album nên ZaChat gửi lần lượt từng ảnh như tin riêng).
- Kết quả trả về:
{ "status": "sent", "message": {…}, "messages": […], "failed_media_ids": [] }. Nếu gửi lỗi giữa chừng (sau khi đã gửi được ít nhất 1 ảnh),failed_media_idschứa cácmedia_idchưa gửi được — CRM kiểm tramessages.lengthvà gửi lại các id trongfailed_media_idsbằng mộtidempotency_keymới.
POST /accounts/{account_id}/messages/{msg_id}/forward#
{ "thread_ids": ["987654321", "g771234"], "user_id": "b21e…" }
{ "data": [ { "thread_id": "987654321", "status": "sent", "message_id": "723…", "error": null } ] }
7. Thao tác trên tin#
| Method | Path | Body | Ghi chú |
|---|---|---|---|
| POST | /accounts/{account_id}/messages/{msg_id}/recall | — | Chỉ tin do nick gửi |
| POST | /accounts/{account_id}/messages/{msg_id}/reactions | { "icon": "❤️" } | Thả cảm xúc: 👍 ❤️ 😂 😮 😭 😡 (nhận cả mã Zalo /-strong, /-heart…) — reactions của tin và webhook dùng emoji |
| DELETE | /accounts/{account_id}/messages/{msg_id}/reactions | — | Gỡ mọi cảm xúc của nick trên tin |
| GET | /accounts/{account_id}/messages/{msg_id}/reactions | — | Ai đã thả cảm xúc gì |
| POST | /accounts/{account_id}/messages/{msg_id}/pin | — | Ghim tin (tối đa 3 / hội thoại) |
| DELETE | /accounts/{account_id}/messages/{msg_id}/pin | — | Bỏ ghim |
| POST | /accounts/{account_id}/threads/{thread_id}/read | — | Đánh dấu đã đọc (đồng bộ với app ZaChat) |
8. Nhắn khách mới theo số điện thoại#
POST /accounts/{account_id}/lookup-phone#
{ "phone": "0912345678" }
{ "data": { "thread_id": "987654321", "name": "Khách A", "avatar": "https://…", "is_friend": false } }
Dùng thread_id để gửi tin như bình thường. Không tìm thấy → 404 USER_NOT_FOUND (chưa dùng Zalo hoặc ẩn tìm kiếm).
Zalo giới hạn tra cứu SĐT mỗi ngày; nhắn quá nhiều người lạ dễ bị khoá nick.
8b. Kết bạn#
Nhiều người bật chặn tin nhắn từ người lạ — gửi lời mời kết bạn trước, chờ webhook friend.added rồi mới nhắn.
| Method | Path | Body / Query | Ghi chú |
|---|---|---|---|
| GET | /accounts/{account_id}/friend-requests?direction=received | — | Lời mời đã nhận đang chờ |
| GET | /accounts/{account_id}/friend-requests?direction=sent | — | Lời mời đã gửi đang chờ |
| POST | /accounts/{account_id}/friend-requests | { "zalo_id": "…", "message": "Chào anh…", "user_id": "…" } | Gửi lời mời (zalo_id lấy từ tra SĐT / tin nhắn; message tối đa 150 ký tự) |
| POST | /accounts/{account_id}/friend-requests/{zalo_id}/accept | — | Đồng ý lời mời |
| POST | /accounts/{account_id}/friend-requests/{zalo_id}/reject | — | Từ chối lời mời |
| DELETE | /accounts/{account_id}/friend-requests/{zalo_id} | — | Thu hồi lời mời đã gửi |
Danh sách lời mời:
{ "data": [ { "zalo_id": "987654321", "name": "Khách A", "avatar": "https://…", "phone": null,
"message": "Mình muốn hỏi sản phẩm", "requested_at": 1762934400000 } ] }
Gửi lời mời:
{ "status": "sent", "zalo_id": "987654321", "daily_used": 12, "daily_limit": 30 }
Hạn mức: lời mời gửi qua API tính chung hạn mức kết bạn mỗi ngày của tổ chức (mặc định 30 lời mời / nick / ngày,
100 / tổ chức / ngày — liên hệ ZaChat nếu cần nâng), chung với các công cụ kết bạn trên app. Hết hạn mức →
429 QUOTA_EXCEEDED, đặt lại 0h giờ Việt Nam.
8c. Kênh chung (chat nội bộ của tổ chức)#
Kênh chung là phòng chat nội bộ giữa các thành viên trên ZaChat (không đi qua Zalo, không phụ thuộc nick online/offline).
Dùng chung quyền messages:read (đọc) / messages:send (tải tệp, gửi, sửa, thu hồi).
GET /team-channel/messages?limit=50&before=#
Trang tin mới nhất của Kênh chung, xếp cũ → mới (giống GET /accounts/{account_id}/threads/{thread_id}/messages).
Tải thêm tin cũ hơn ("load more"): truyền before = next_before của trang trước (null = đã hết lịch sử).
GET /team-channel/messages/{msg_id}#
Đọc chi tiết một tin nhắn Kênh chung theo UUID.
Đối tượng tin nhắn Kênh chung#
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"author": { "user_id": "b21e…", "name": "Trần Bình" },
"source": "api", // "api" nếu gửi qua API mở; null nếu gửi từ ứng dụng ZaChat
"idempotency_key": "crm-team-101", // key của lệnh gửi qua API; null nếu gửi từ ứng dụng ZaChat
"text": "@Nguyễn An duyệt đơn DH102 nhé", // null khi tin chỉ có tệp đính kèm hoặc đã thu hồi
"attachments": [
{
"id": "8a1c…",
"kind": "image", // image | video | file
"file_name": "don-hang.webp",
"mime_type": "image/webp",
"file_size": 84210,
"url": "https://api.zachat.vn/…",
"thumbnail_url": "https://api.zachat.vn/…",
"width": 2048,
"height": 1024
}
],
"mentions": [ { "user_id": "8f0c…", "name": "Nguyễn An" } ],
"mention_all": false,
"quote": {
"msg_id": "330e8400-…",
"sender_name": "Nguyễn An",
"text": "Đơn này khách đã cọc chưa?",
"timestamp": 1762934300000,
"is_recalled": false
},
"is_recalled": false,
"edited_at": null, // Unix ms lần sửa gần nhất; null nếu chưa sửa
"timestamp": 1762934400000 // Unix ms thời điểm tạo
}
Tệp đính kèm Kênh chung được lưu trên kho của tổ chức (không hết hạn như link CDN của Zalo), bị xoá khi thu hồi tin.
POST /team-channel/attachments (multipart/form-data, field file, tối đa 20MB)#
Tải từng ảnh / video / tệp lên trước khi gửi tin vào Kênh chung (tối đa 10 tệp mỗi tin; ảnh tự nén sang WebP tối đa 2048px kèm ảnh thu nhỏ). Có thể truyền thêm field file_name (UTF-8) nếu thư viện multipart làm lỗi tên tiếng Việt.
Giới hạn: 30 tệp / phút mỗi tổ chức; tối đa 50 tệp đã tải lên mà chưa gửi (quá thì 429 RATE_LIMITED). Tệp tải lên mà không gửi tự xoá sau 24 giờ.
{
"attachment_id": "8a1c…",
"kind": "image",
"file_name": "kho.webp",
"mime_type": "image/webp",
"file_size": 84210,
"url": "https://api.zachat.vn/…",
"thumbnail_url": "https://api.zachat.vn/…",
"width": 2048,
"height": 1024
}
POST /team-channel/messages#
Gửi tin vào Kênh chung (hiện ngay theo thời gian thực trên ứng dụng ZaChat của cả đội; người được nhắc nhận thông báo):
{
"idempotency_key": "crm-team-101",
"text": "@Nguyễn An duyệt đơn DH102 nhé",
"attachment_ids": ["8a1c…"], // tuỳ chọn, 1–10 tệp (có tệp thì text được phép để trống)
"mention_user_ids": ["8f0c…"], // tuỳ chọn, mảng user_id lấy từ GET /team
"mention_all": false, // tuỳ chọn, nhắc @Tất cả thành viên
"quote_msg_id": "330e8400-…", // tuỳ chọn, trả lời một tin trong Kênh chung
"user_id": "b21e…" // tuỳ chọn, mặc định chủ tổ chức
}
Trả về 201 { "status": "sent", "message": {…} } (hoặc 200 khi gửi lại cùng idempotency_key). Không qua Zalo nên luôn hoàn tất ngay, không có trạng thái 202 pending.
Sửa & thu hồi tin Kênh chung#
Chỉ người đã gửi tin (author.user_id) mới sửa hoặc thu hồi được tin đó — nếu tin do thành viên gửi, truyền đúng user_id của thành viên đó trong body (không truyền user_id thì tính là chủ tổ chức):
| Method | Path | Body | Kết quả |
|---|---|---|---|
| PATCH | /team-channel/messages/{msg_id} | { "text": "…", "mention_user_ids": […], "mention_all": false, "user_id": "…" } | 200 { "status": "edited", "message": {…} } (mention_user_ids / mention_all không truyền thì giữ nguyên) |
| POST | /team-channel/messages/{msg_id}/recall | { "user_id": "…" } (tuỳ chọn nếu chủ tổ chức gửi) | 200 { "status": "recalled" } |
8d. Zalo Official Account (Zalo OA)#
Nick Zalo OA dùng cùng các endpoint với nick Zalo cá nhân (account_id vẫn có dạng acc_<oa_id>), phân biệt qua channel: "zalo_oa" và mảng capabilities. API key để phạm vi "Mọi nick" tự động bao gồm cả nick OA; key chọn từng nick thì tích thêm nick OA trong Cài đặt → API & Webhook.
Khác biệt giữa nick cá nhân và Zalo OA (theo quy định Open API của Zalo)#
| Hạng mục | Nick Zalo cá nhân (zalo_personal) | Zalo OA (zalo_oa) |
|---|---|---|
| Nhắn trước cho khách | Được (tra SĐT, nhắn người lạ) | Không. Khách phải tương tác với OA trong 7 ngày gần nhất. Trong 48h đầu miễn phí; ngoài 48h Zalo tính phí gói OA (doanh nghiệp tự thanh toán cho Zalo) |
| Gửi chữ, trả lời trích dẫn | Có (≤ 10.000 ký tự) | Có, chữ và chú thích ảnh ≤ 2.000 ký tự (dài hơn bị từ chối 400 VALIDATION_ERROR, không tự cắt) |
| Gửi ảnh | Mọi loại | JPG / PNG ≤ 1MB gửi nguyên bản; ảnh lớn hơn hoặc định dạng khác (WebP, HEIC, GIF…) ZaChat tự chuyển sang JPG nền trắng ≤ 1MB. Ảnh hỏng hoặc nén xong vẫn > 1MB → 422 MEDIA_NOT_ALLOWED |
| Gửi tệp | Mọi loại ≤ 50MB | Chỉ PDF / DOC / DOCX / CSV ≤ 5MB (sai loại hoặc quá 5MB → 422 MEDIA_NOT_ALLOWED) |
Album (POST …/albums) | Một album, 2–20 ảnh | 2–10 ảnh, gửi lần lượt từng ảnh |
| Video, ghi âm, sticker, vị trí | Có | Không (422 NOT_SUPPORTED) |
| Thu hồi, cảm xúc, ghim, chuyển tiếp | Có | Không (422 NOT_SUPPORTED; riêng GET …/reactions vẫn trả 200 { "data": [] }) |
Nhóm chat (g…), nhắc tên (mentions) | Có | Không — chỉ chat 1-1 (422 NOT_SUPPORTED) |
| Tra SĐT, kết bạn | Có | Không (422 NOT_SUPPORTED) |
zalo_id của khách | uid Zalo cá nhân | user_id riêng theo từng OA, không trùng uid cá nhân — không dùng zalo_id để gộp khách giữa OA và nick cá nhân |
| Bộ lọc riêng tư | Có | Không — mọi hội thoại OA đều thuộc tổ chức |
Gói dịch vụ Zalo OA (
-224): Phía Zalo yêu cầu OA có gói Tăng trưởng hoặc Toàn diện trênzalo.cloudmới gửi được tin qua Open API. Nếu OA đang ở gói miễn phí, API trả422 OA_PACKAGE_REQUIRED. Mọi lỗi kiểm tra đầu vào (NOT_SUPPORTED,MEDIA_NOT_ALLOWED,REPLY_WINDOW_EXPIRED,VALIDATION_ERROR) đều trả về trước khi giữ khoáidempotency_key, nên CRM sửa xong có thể gửi lại cùng key.
Bảng capabilities của nick#
CRM dựa vào capabilities của từng nick trong GET /accounts để ẩn / hiện tính năng trên giao diện (không viết cứng theo channel). Quy ước trong v1: bỏ qua tên lạ, và ZaChat chỉ thêm chứ không bớt tên cũ (ví dụ khi mở thả cảm xúc cho OA ở bản sau, nick OA sẽ có thêm "reactions").
Tên trong capabilities | Endpoint / tham số liên quan | Cá nhân | OA |
|---|---|---|---|
send_text, send_image, send_file, quote | POST …/messages | ✓ | ✓ (chữ ≤ 2.000; file PDF/DOC/DOCX/CSV ≤ 5MB) |
album | POST …/albums | ✓ (≤ 20 ảnh) | ✓ (≤ 10 ảnh, gửi lần lượt) |
send_video, send_voice, sticker, location | POST …/messages theo type | ✓ | – |
mentions | mentions và thread_id nhóm (g…) | ✓ | – |
recall | POST …/recall | ✓ | – |
reactions | POST / DELETE …/reactions (GET luôn đọc được) | ✓ | – |
pin | POST / DELETE …/pin | ✓ | – |
forward | POST …/forward | ✓ | – |
lookup_phone | POST …/lookup-phone | ✓ | – |
friend_requests | …/friend-requests | ✓ | – |
reply_window | GET …/reply-window; chặn gửi quá 7 ngày | – | ✓ |
Kiểm tra hạn trả lời 7 ngày (GET /accounts/{account_id}/threads/{thread_id}/reply-window)#
Chỉ dành cho nick có "reply_window" trong capabilities (quyền messages:read):
{
"last_interaction_at": 1763450000000,
"expires_at": 1764054800000,
"can_send": true,
"free_until": 1763622800000
}
- Không xác định được mốc tương tác (khách chưa từng tương tác hoặc OA gói miễn phí chưa có tin lưu) → cả 4 trường đều là
null. free_until=last_interaction_at+ 48 giờ (mốc tham khảo để CRM tự hiển thị nếu muốn).- Gọi trên nick cá nhân →
422 NOT_SUPPORTED. Gọi khi OA mất kết nối / bị gỡ quyền →409 ACCOUNT_OFFLINE. - Thực hành tốt: Danh sách hội thoại (
GET …/threads) không kèm hạn trả lời để không tốn hạn mức 100 req/phút của Zalo OA. Mỗi sự kiệnmessage.receivedtừ khách tự động làm mới hạn 7 ngày — CRM chỉ cần cộng 7 ngày từ tin khách gần nhất và gọireply-windowkhi mở hội thoại cũ cần kiểm tra chắc chắn. Khi gửi tin mà hội thoại đã quá hạn 7 ngày kể từ lần tương tác cuối (tính cả bấm menu / gọi điện trên OA), API chặn trước với422 REPLY_WINDOW_EXPIRED(kèmerror.details.expires_at).
9. Webhook#
Mỗi tổ chức cài một URL webhook (https) và có một secret ký (dạng whsec_…, tạo trong Cài đặt → API & Webhook); muốn chuyển tiếp
sự kiện tới nhiều hệ thống thì CRM tự phân phối. Mỗi sự kiện là một POST:
Content-Type: application/json
X-ZaChat-Event: message.received
X-ZaChat-Delivery: 5f1c2e0a-… (id lần gửi — dùng chống trùng)
X-ZaChat-Timestamp: 1762934400 (giây)
X-ZaChat-Signature: sha256=<hex>
{ "id": "5f1c2e0a-…", "event": "message.received", "created_at": 1762934400123, "account_id": "acc_123456789", "channel": "zalo_personal", "data": { … } }
| Sự kiện | data |
|---|---|
message.received | Đối tượng tin nhắn (tin đến — data.channel cho biết từ nick cá nhân hay OA) |
message.sent | Đối tượng tin nhắn (tin đi — từ API source: "api", admin trên oa.zalo.me source: "oa_manager", hoặc từ app ZaChat / điện thoại source: null) |
message.failed | { account_id, thread_id, idempotency_key, error } — lệnh gửi API đã trả 202 rồi thất bại |
message.recalled | { account_id, thread_id, msg_id } |
message.reaction | { account_id, thread_id, msg_id, sender_zalo_id, icon, action: "add" | "remove", reactions } |
message.pinned | { account_id, thread_id, pinned_messages: [ { msg_id, sender_name, preview } ] } |
account.status_changed | { account_id, is_online, reason } — nick mất kết nối / kết nối lại (reason: "authorization_revoked" khi Zalo OA bị gỡ quyền, "kicked" / "duplicate_login" với nick cá nhân, "restore_failed" khi không khôi phục được sau cập nhật…) |
friend.request_received | { account_id, zalo_id, name, message } — có người gửi lời mời kết bạn cho nick (name có thể null — xem chi tiết ở GET /friend-requests) |
friend.added | { account_id, zalo_id, name } — đã thành bạn bè (khách đồng ý lời mời của nick, hoặc nick đồng ý lời mời của khách) |
team_channel.message_created | Đối tượng tin nhắn Kênh chung (gửi từ ứng dụng ZaChat hoặc qua API; account_id và channel ngoài vỏ = null) |
team_channel.message_edited | Đối tượng tin nhắn Kênh chung sau khi sửa (edited_at cập nhật; account_id và channel = null) |
team_channel.message_recalled | { msg_id, user_id } — tin Kênh chung bị thu hồi (account_id và channel = null) |
webhook.test | { message, test: true } — gửi khi bạn bấm Gửi thử (account_id = null, channel = null), chỉ một lần, không thử lại; chỉ cần trả 2xx |
Quy tắc:
- Envelope luôn có trường
channel("zalo_personal"|"zalo_oa", hoặcnullkhiaccount_id = null). Bản webhook cũ được phát lại nếu thiếuchannelthì coi là"zalo_personal". - Không chọn sự kiện nào (
eventsrỗng) = nhận mọi sự kiện (gồm cảteam_channel.*, vớiaccount_id = null,channel = nullngoài vỏ vì Kênh chung thuộc cả tổ chức). - Tin bạn tự gửi qua API hoặc từ trang quản lý OA cũng được báo lại (
message.sent,team_channel.message_created).- Tin admin trả lời trực tiếp trên
oa.zalo.mecósource: "oa_manager"ở cả webhookmessage.sentlẫn khi đọc lại quaGET …/messages(lưu ý: tin OA nạp bù từ lịch sử/conversationcủa Zalo không có thông tin admin nênsource: null). - Nếu CRM tự động trả lời theo webhook, chỉ xử lý
message.received(direction = "in") và bỏ quadata.source = "api"/"oa_manager"để tránh vòng lặp.
- Tin admin trả lời trực tiếp trên
- Trả về 2xx trong 10 giây (xử lý nặng thì đưa vào hàng đợi của bạn). Không 2xx → thử lại sau 1, 2, 4, 8, 16, 32 phút. Lỗi liên tục nhiều lần → ZaChat tạm tắt webhook; chủ tổ chức bấm Bật lại trong Cài đặt sau khi sửa lỗi.
- Giao ít nhất một lần, không đảm bảo thứ tự: cùng một tin có thể đến 2 lần → lưu theo
data.id(upsert), sắp xếp theodata.timestamp. - Tin bị lỡ khi nick mất kết nối sẽ được gửi khi nick kết nối lại.
- Luôn kiểm chữ ký và từ chối
X-ZaChat-Timestamplệch quá 5 phút.
Chữ ký = hex(HMAC_SHA256(secret, timestamp + "." + raw_body)) — dùng body thô nhận được, không parse rồi stringify lại.
Node.js (Express):
const crypto = require("crypto");
app.post("/zachat/webhook", express.raw({ type: "application/json" }), (req, res) => {
const ts = req.get("X-ZaChat-Timestamp");
const expected = "sha256=" + crypto.createHmac("sha256", process.env.ZACHAT_WEBHOOK_SECRET)
.update(`${ts}.${req.body}`).digest("hex");
const given = req.get("X-ZaChat-Signature") || "";
const ok = given.length === expected.length && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
if (!ok || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(401);
const event = JSON.parse(req.body);
queue.push(event); // xử lý sau
res.sendStatus(200);
});
PHP:
$body = file_get_contents('php://input');
$ts = $_SERVER['HTTP_X_ZACHAT_TIMESTAMP'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $body, getenv('ZACHAT_WEBHOOK_SECRET'));
if (!hash_equals($expected, $_SERVER['HTTP_X_ZACHAT_SIGNATURE'] ?? '') || abs(time() - (int)$ts) > 300) {
http_response_code(401); exit;
}
$event = json_decode($body, true);
http_response_code(200);
10. Lưu ý vận hành#
- Nick Zalo cá nhân có thể bị Zalo đăng xuất (đăng nhập Zalo Web nơi khác, Zalo nghi spam…); Zalo OA có thể bị thu hồi quyền trên trang quản trị OA (
reason: "authorization_revoked"). Theo dõiaccount.status_changed: nick cá nhân mất kết nối thì quét lại QR trên ZaChat; Zalo OA thì bấm cấp quyền lại trên web / máy tính ZaChat (không quét QR). Lệnh gửi trong lúc đó trả409 ACCOUNT_OFFLINE. - ZaChat cập nhật máy chủ thường mất khoảng 10 giây (ưu tiên ban đêm). Trong lúc đó API trả
503 SERVICE_RESTARTINGkèmRetry-After— gửi lại cùngidempotency_keylà an toàn. Nick không bị coi là mất kết nối: CRM không nhậnaccount.status_changedcho lần cập nhật, trừ nick không kết nối lại được (reason: "restore_failed"). Tin khách nhắn trong lúc cập nhật được lấy bù khi nick kết nối lại và gửi qua webhookmessage.receivednhư bình thường. - Mỗi nick Zalo cá nhân chỉ dùng song song được 1 điện thoại + 1 Zalo PC + 1 Zalo Web — ZaChat chiếm vị trí Zalo Web.
- Phiên bản: mọi thay đổi không tương thích sẽ ra
/api/v2và được báo trước ít nhất 30 ngày. Có thể thêm trường mới vào đối tượng trả về bất cứ lúc nào — CRM nên bỏ qua trường không biết.