Chuyển đến nội dung chính (Skip to content)
ZaChat Logo
ZaChat Multi-Zalo CRM
Dành cho lập trình viên · v1

ZaChat API — Tích hợp chat Zalo vào CRM

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:

  1. Mở ZaChat (web hoặc ứng dụng máy tính) → Cài đặt → API & Webhook.
  2. 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.
  3. 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_id không phải thành viên đang hoạt động → lỗi 422 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." } }
HTTPcodeÝ nghĩa
400VALIDATION_ERRORThiếu / sai tham số (vd. chữ Zalo OA > 2.000 ký tự, album OA > 10 ảnh)
401UNAUTHORIZEDKey sai hoặc đã thu hồi
402PLAN_EXPIREDGói ZaChat của tổ chức hết hạn
402PLAN_NOT_INCLUDEDGói hiện tại không bao gồm API (vd. đã hạ xuống gói thấp hơn)
403FORBIDDEN_SCOPEKey không có quyền này
403ORG_SUSPENDEDTổ chức bị khoá
404ACCOUNT_NOT_FOUNDNick không tồn tại / ngoài phạm vi key
404THREAD_NOT_VISIBLEHội thoại không tồn tại hoặc riêng tư
404MESSAGE_NOT_FOUND, MEDIA_NOT_FOUND, USER_NOT_FOUNDKhông tìm thấy
409ACCOUNT_OFFLINENick đang mất kết nối Zalo (hoặc Zalo OA bị gỡ quyền)
422INVALID_USER_IDuser_id không phải thành viên đang hoạt động
422NOT_SUPPORTEDThao 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
422REPLY_WINDOW_EXPIREDZalo 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
422OA_PACKAGE_REQUIREDZalo trả -224: Zalo OA đang ở gói miễn phí, chủ OA cần nâng gói trên zalo.cloud
422MEDIA_NOT_ALLOWEDTệ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)
429RATE_LIMITEDGọi quá nhanh — thử lại sau
429QUOTA_EXCEEDEDHết hạn mức kết bạn trong ngày
502ZALO_ERRORZalo từ chối / lỗi khi gọi Zalo
503SERVICE_RESTARTINGZaChat đ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
500INTERNAL_ERRORLỗ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ếu channel thì hiểu là "zalo_personal").
  • capabilities: danh sách thao tác loại nick đó hỗ trợ (luôn trả đủ ngay cả khi is_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:

  1. Lần đầu: gọi không có cursor, rồi gọi tiếp với cursor = next_cursor cho tới khi next_cursor là null. Một trang có thể ít hơn limit, kể cả rỗng (hội thoại riêng tư bị lọc) — chỉ dừng khi next_cursor = null.
  2. Lưu sync_cursor của trang cuối. Lần đồng bộ sau gọi với cursor = 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 theo id.

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ùng idempotency_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 webhook message.sent hoặc message.failed, cả hai đều kèm idempotency_key củ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 đượcNên làm
201 / 200Đã gửi xong — lưu message.id
202 pendingChờ 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 / 500Khô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_RESTARTINGChờ theo header Retry-After rồi gửi lại cùng key
409 ACCOUNT_OFFLINEBáo nhân viên quét lại nick; gửi lại cùng key khi nick online
4xx khácLỗ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_ids chứa các media_id chưa gửi được — CRM kiểm tra messages.length và gửi lại các id trong failed_media_ids bằng một idempotency_key mớ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#

MethodPathBodyGhi 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.

MethodPathBody / QueryGhi 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):

MethodPathBodyKế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ụcNick 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ẫnCó (≤ 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 ảnhMọi loạiJPG / 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ệpMọi loại ≤ 50MBChỉ PDF / DOC / DOCX / CSV ≤ 5MB (sai loại hoặc quá 5MB → 422 MEDIA_NOT_ALLOWED)
Album (POST …/albums)Một album, 2–20 ảnh2–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ếpCó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ạnCóKhông (422 NOT_SUPPORTED)
zalo_id của kháchuid Zalo cá nhânuser_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ên zalo.cloud mớ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 capabilitiesEndpoint / tham số liên quanCá nhânOA
send_text, send_image, send_file, quotePOST …/messages✓✓ (chữ ≤ 2.000; file PDF/DOC/DOCX/CSV ≤ 5MB)
albumPOST …/albums✓ (≤ 20 ảnh)✓ (≤ 10 ảnh, gửi lần lượt)
send_video, send_voice, sticker, locationPOST …/messages theo type✓–
mentionsmentions và thread_id nhóm (g…)✓–
recallPOST …/recall✓–
reactionsPOST / DELETE …/reactions (GET luôn đọc được)✓–
pinPOST / DELETE …/pin✓–
forwardPOST …/forward✓–
lookup_phonePOST …/lookup-phone✓–
friend_requests…/friend-requests✓–
reply_windowGET …/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ện message.received từ 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ọi reply-window khi 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ới 422 REPLY_WINDOW_EXPIRED (kèm error.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ệndata
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ặc null khi account_id = null). Bản webhook cũ được phát lại nếu thiếu channel thì coi là "zalo_personal".
  • Không chọn sự kiện nào (events rỗng) = nhận mọi sự kiện (gồm cả team_channel.*, với account_id = null, channel = null ngoà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.me có source: "oa_manager" ở cả webhook message.sent lẫn khi đọc lại qua GET …/messages (lưu ý: tin OA nạp bù từ lịch sử /conversation của Zalo không có thông tin admin nên source: null).
    • Nếu CRM tự động trả lời theo webhook, chỉ xử lý message.received (direction = "in") và bỏ qua data.source = "api" / "oa_manager" để tránh vòng lặp.
  • 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 theo data.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-Timestamp lệ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õi account.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_RESTARTING kèm Retry-After — gửi lại cùng idempotency_key là an toàn. Nick không bị coi là mất kết nối: CRM không nhận account.status_changed cho 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 webhook message.received như 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/v2 và đượ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.