# Ý tưởng triển khai tính năng cho sản phẩm Zalo/FlyChat

Tài liệu này tổng hợp ý tưởng từ 3 góc nhìn:

- Năng lực kỹ thuật của `zca-js`: Zalo cá nhân, WebSocket realtime, gửi tin, danh bạ, nhóm, bạn bè, phản ứng, thu hồi, công cụ nhóm, cài đặt tài khoản, quick message, auto reply, ZBusiness.
- Nền tảng hệ thống hiện có: Laravel + worker Node, lưu tin nhắn vào MySQL, chat đa tài khoản, danh bạ, thẻ, tin nhắn mẫu, AI agent, tự trả lời, quản lý nhân viên, OAuth/external API.
- Giá trị sản phẩm: tăng tốc xử lý hội thoại, giảm mất khách, kiểm soát chất lượng tư vấn, mở rộng vận hành nhiều tài khoản Zalo an toàn hơn.

Lưu ý quan trọng: `zca-js` là API không chính thức cho tài khoản Zalo cá nhân. Các tính năng tự động hóa cần giới hạn tần suất, có log kiểm soát và cơ chế tắt khẩn cấp để giảm rủi ro tài khoản bị khóa hoặc bị Zalo thay đổi endpoint.

> **Rà soát code và thị trường: 17/09/2026.** Các mục có dấu ✅ là những gì đã thấy trong
> code hiện tại (migration, route, service, UI hoặc test), không chỉ là ý tưởng trên giấy.
> Phần **MVP tiếp theo**, **thiết kế kỹ thuật** và **kết luận ưu tiên** ở cuối tài liệu là nguồn ưu tiên mới; các bảng backlog cũ vẫn được
> giữ lại để tránh mất chi tiết kỹ thuật nhưng phải đọc cùng trạng thái bên dưới.

## 0. Trạng thái thực tế sau khi rà soát project

| Năng lực | Trạng thái hiện tại | Khoảng trống quan trọng |
|---|---|---|
| Inbox Zalo cá nhân | ✅ Đa tài khoản, QR/relogin, realtime, đồng bộ tin cũ/mobile, phân trang, file/ảnh/quote/reaction/thu hồi/xóa/chuyển tiếp text | Chưa có trạng thái xử lý hội thoại, người phụ trách hội thoại, ghi chú nội bộ, khóa chống trả lời trùng |
| Danh bạ và nhóm | ✅ Bạn bè, lời mời, tạo nhóm, thành viên, đổi tên/avatar, sticker/danh thiếp/video/thẻ ngân hàng | Chưa có chặn user, alias, lời mời đã gửi, duyệt thành viên, poll/reminder/board |
| AI | ✅ Agent, auto-reply theo hội thoại, flow state machine, tóm tắt, nhiều provider OAuth, quota/fallback, lịch sử agent run | Chưa có knowledge base có phiên bản, phân loại intent/sentiment, gợi ý trả lời có đo lường, guardrail trước gửi, AI gọi công cụ nghiệp vụ |
| Vận hành đội nhóm | ✅ User/admin/super admin, đơn vị, gói dịch vụ, phân quyền tài khoản Zalo, health alert, báo cáo phản hồi/SLA theo dữ liệu | Chưa có assignment hội thoại, SLA theo chính sách/giờ làm việc, audit log nghiệp vụ, notification center |
| Zalo OA | ✅ OAuth, token refresh, webhook, đồng bộ lịch sử, gửi/nhận qua OpenAPI, dùng chung inbox | Chưa có ZBS Template Message, quota/chi phí theo template, native Chatbot/form/menu, broadcast chính thức, voice/call |
| Campaign | ✅ Lọc theo tag/tài khoản, preview, chốt target, schedule, pause/cancel, retry, delay/rate limit và giới hạn riêng cho OA | Đây là outbound campaign của FlyChat; chưa phải module Broadcast/ZBS chính thức của Zalo và chưa có opt-in/suppression center đầy đủ |
| CRM và chuyển đổi | ✅ Tag, template, AI summary, báo cáo template/AI | Chưa có hồ sơ khách hợp nhất, custom fields, pipeline, lịch hẹn, task, đơn hàng/sản phẩm, attribution |
| Nền tảng tích hợp | ✅ External OAuth API đọc/gửi tin/chạy agent | Chưa có outbound webhook có retry, idempotency, connector n8n/Make/Calendar/CRM |

Ký hiệu: ✅ đã có; 🟡 có một phần, cần hoàn thiện; ⏳ chưa triển khai.

### Kết luận nhanh

FlyChat đã vượt qua giai đoạn “gom nhiều nick vào một màn hình”. Khoảng cách sản phẩm hiện
tại nằm ở **lớp vận hành và chuyển đổi**: ai chịu trách nhiệm, khách đang ở giai đoạn nào,
việc tiếp theo là gì, AI có được phép làm gì, và tin nhắn có tạo ra lịch hẹn/doanh thu hay
không. Không nên tiếp tục ưu tiên thêm các endpoint Zalo lẻ nếu chưa giải quyết lớp này.

## 0.1. Đối chiếu nhanh với sản phẩm trên thị trường

Phạm vi đối chiếu là trang sản phẩm/tài liệu chính thức được truy cập ngày 17/09/2026.

| Sản phẩm/nền tảng | Điều thị trường đã coi là tiêu chuẩn | Bài học/cơ hội cho FlyChat |
|---|---|---|
| [Zalo OA OpenAPI](https://oa.zalo.me/home/function/extension) và [Zalo Chatbot](https://oa.zalo.me/home/resources/library/tu-dong-hoa-cham-soc-khach-hang-voi-zalo-chatbot_6352033339970702125) | API vận hành nhiều OA, webhook, chatbot theo flow/rule, form lấy thông tin, tag, broadcast và dynamic API | Không cần tự xây lại toàn bộ chatbot native. Nên làm lớp điều phối: đồng bộ lead/form/tag, nối vào CRM, approval, AI và báo cáo chuyển đổi |
| [Haravan Omnichannel Inbox](https://www.haravan.com/pages/crm-marketing-omnichannel-inbox) | Inbox đa kênh, nhiều bộ lọc, phân công, gợi ý sản phẩm, tạo giỏ hàng/link thanh toán, phát hiện cơ hội mua | Nếu chỉ làm chat, FlyChat sẽ bị so sánh với omnichannel. Lợi thế nên là Zalo-first: nhiều nick cá nhân + OA, an toàn phiên và vận hành đội nhóm; sau đó thêm product/booking action |
| [Pancake](https://pancake.vn/) | Unified chat, CRM/lead, order management và AI chatbot hướng tới chốt đơn; có các gói theo ngành | Có thể đóng gói playbook theo ngành thay vì làm CRM chung chung: spa/clinic, giáo dục, bất động sản, bán lẻ |
| [Sapo Chatbot](https://www.sapo.vn/phan-mem-chat-bot.html) | Gom Facebook/Zalo/Zalo OA/Instagram, AI trả lời, ghi nhận yêu cầu lên đơn rồi chuyển nhân viên xử lý | Cần thêm “next action” sau tin nhắn: tạo lead, đặt lịch, tạo task, gắn nguồn; không chỉ sinh câu trả lời |
| [respond.io](https://respond.io/help/product) | Inbox, contact module, broadcast, workflow, dynamic variables, AI agent, mobile, API/webhook và tích hợp lịch/n8n | Đây là khoảng trống nền tảng của FlyChat: saved views, workflow trigger/action, webhook có retry, biến dữ liệu, API công khai và lịch hẹn |
| [SleekFlow](https://sleekflow.io/en-us/channels-integrations) | Inbox đa kênh, broadcast, flow builder, analytics, ticketing, social CRM, catalog/payment, RBAC và bảo mật doanh nghiệp | Bổ sung ticket mode, analytics doanh thu, PII masking/export, mobile/PWA và quyền theo vai trò khi sản phẩm đã có khách hàng trả phí |

### Nhận định cạnh tranh

- Inbox, AI chatbot và gửi campaign là nhóm tính năng dễ bị sao chép. Đây không nên là thông
  điệp khác biệt duy nhất.
- Điểm có thể sở hữu riêng là **Zalo Operations OS cho doanh nghiệp dùng nhiều nick cá nhân
  và OA**: quản lý phiên, phân công hội thoại, an toàn gửi, đồng nhất hồ sơ khách, AI có kiểm
  soát và đo được lịch hẹn/chốt đơn.
- Zalo đang đẩy mạnh OA OpenAPI, Chatbot, form, tag và ZBS Template Message. Vì vậy nên dùng
  API chính thức cho OA và coi `zca-js` là kênh cá nhân có rủi ro riêng; không trộn policy,
  quota hoặc capability của hai kênh.

## 1. Định vị sản phẩm nên hướng tới

FlyChat nên được định vị như một "Zalo Sales & Care Inbox" cho đội ngũ vận hành nhiều tài khoản Zalo cá nhân, không chỉ là màn chat gom nhiều nick.

Các trục giá trị chính:

- Không bỏ sót hội thoại: gom nhiều tài khoản, trạng thái phiên rõ, cảnh báo mất kết nối, nhắc việc xử lý.
- Trả lời nhanh nhưng có kiểm soát: mẫu, AI tạo nháp, AI tự gửi theo điều kiện, kiểm duyệt nội dung nhạy cảm.
- Quản lý khách hàng nhẹ: thẻ, pipeline, ghi chú, lịch hẹn, người phụ trách, lịch sử tương tác.
- Tối ưu đội nhóm: phân quyền, phân công hội thoại, SLA, báo cáo hiệu suất nhân viên.
- Tận dụng Zalo thật: kết bạn, nhóm, danh thiếp, sticker, phản ứng, thu hồi, trạng thái đã xem/đang gõ, công cụ nhóm.

## 2. Nền tảng hiện có có thể khai thác tiếp

Hệ thống hiện đã có nhiều nền tảng tốt để mở rộng:

- Đa tài khoản Zalo: thêm, mở phiên, quét QR, đăng nhập lại, trạng thái READY/ERROR/RELOGIN_REQUIRED.
- Worker WebSocket theo `zca-js`: nhận tin mới, nhận lịch sử tồn đọng qua `old_messages`, tự reconnect, callback HMAC về Laravel.
- Kho dữ liệu riêng: `zalo_conversations`, `zalo_messages`, `zalo_contacts`, reaction, friend request, tag, message template.
- Chat UI: đọc/gửi tin, ảnh/tệp, quote, reaction, thu hồi, xóa phía mình, chuyển tiếp text, sticker, danh thiếp, video URL, thẻ ngân hàng.
- Danh bạ: bạn bè, nhóm, mở hội thoại, kết bạn, lời mời kết bạn, tạo nhóm.
- Nhóm: đổi tên, đổi avatar, thêm/xóa thành viên, đọc thành viên.
- AI: agent, prompt, nhiều provider (OpenAI/Codex/Claude), quota/fallback, tạo nháp, tự gửi,
  flow state machine, tóm tắt hội thoại, bật/tắt theo hội thoại, lịch sử agent run.
- Quản trị: nhân viên/admin/super admin, đơn vị, gói dịch vụ, hạn mức tài khoản, phân quyền
  tài khoản Zalo theo user, tag, message template và báo cáo vận hành.
- Zalo OA: OAuth PKCE và refresh token, webhook chính thức, đồng bộ lịch sử, gửi/nhận qua
  OpenAPI; dùng chung kho hội thoại với nick cá nhân nhưng đã có phân biệt capability theo kênh.
- Campaign outbound: lọc theo tag/tài khoản, preview, schedule, chốt danh sách, queue, pause,
  cancel, retry, rate limit và theo dõi từng target.
- External OAuth API: đọc danh sách tài khoản/hội thoại/tin nhắn, gửi tin và gọi agent; đây là
  nền để làm webhook outbound, connector CRM và automation.

Điểm cần nhớ khi thiết kế tiếp:

- `zca-js` không có API lấy danh sách hội thoại gần đây, hệ thống phải tiếp tục coi MySQL là nguồn dữ liệu chính.
- Lịch sử cũ không thể lấy lại tùy ý. Mọi tính năng phân tích nên ghi rõ chỉ dựa trên dữ liệu từ thời điểm hệ thống bắt đầu nhận được.
- Một tài khoản Zalo chỉ nên có một listener web đang chạy. Cần tránh người dùng mở Zalo Web cùng tài khoản khi worker đang nghe.
- Các thao tác tự động gửi tin cần chống spam và có chính sách giới hạn.

## 3. Bản đồ năng lực `zca-js` còn có thể khai thác

### Realtime và trạng thái hội thoại

Đã dùng: `message`, `old_messages`, `reaction`, `undo`, `group_event`, `friend_event`, `connected`, `closed`, `error`.

Còn có thể dùng:

- `typing`: biết khách hoặc thành viên nhóm đang gõ.
- `seen_messages`: biết đối phương đã xem đến tin nào.
- `delivered_messages`: biết tin đã tới thiết bị đối phương.
- `old_reactions`: đồng bộ lại reaction cũ.
- `upload_attachment`: theo dõi tiến độ/URL xử lý tệp.
- `disconnected`, `cipher_key`: phục vụ giám sát và chẩn đoán phiên.

### Gửi và tương tác tin nhắn

Đã dùng: text, ảnh/tệp, quote, reaction, sticker, danh thiếp, video URL, thẻ ngân hàng, xóa, thu hồi, chuyển tiếp text.

Còn có thể dùng:

- `sendVoice`: gửi tin nhắn thoại.
- `sendLink` và `parseLink`: gửi link có preview tốt hơn.
- `sendTypingEvent`: báo cho khách biết nhân viên/AI đang soạn.
- `sendSeenEvent`, `sendDeliveredEvent`: đồng bộ trạng thái đã xem/đã nhận của chính tài khoản hệ thống.

### Bạn bè và danh bạ

Đã dùng: danh sách bạn bè/nhóm, tìm user bằng số điện thoại trong luồng kết bạn, gửi/chấp nhận/từ chối/hủy lời mời, xóa bạn.

Còn có thể dùng:

- `blockUser`, `unblockUser`: chặn/bỏ chặn khách spam hoặc quấy rối.
- `changeFriendAlias`, `removeFriendAlias`: đặt tên gợi nhớ Zalo thật theo quy tắc CRM.
- `getFriendRequestStatus`, `getSentFriendRequest`: quản lý lời mời đã gửi.
- `findUser`, `findUserByUsername`, `getMultiUsersByPhones`: import lead theo số điện thoại.
- `getCloseFriends`, `getFriendOnlines`, `lastOnline`: tín hiệu ưu tiên liên hệ, cần dùng thận trọng.

### Quản lý nhóm

Đã dùng: tạo nhóm, đổi tên/avatar, thêm/xóa thành viên, đọc thành viên.

Còn có thể dùng:

- Duyệt thành viên: `getPendingGroupMembers`, `reviewPendingMemberRequest`.
- Vai trò nhóm: `changeGroupOwner`, `addGroupDeputy`, `removeGroupDeputy`.
- Link nhóm: `getGroupLinkInfo`, `getGroupLinkDetail`, `enableGroupLink`, `disableGroupLink`, `joinGroupLink`.
- Chặn thành viên nhóm: `addGroupBlockedMember`, `removeGroupBlockedMember`, `getGroupBlockedMember`.
- Cài đặt nhóm: `updateGroupSettings`, `disperseGroup`, `leaveGroup`, `upgradeGroupToCommunity`.

### Công cụ nhóm

Còn chưa khai thác:

- Poll: `createPoll`, `addPollOptions`, `votePoll`, `lockPoll`, `getPollDetail`, `sharePoll`.
- Nhắc việc: `createReminder`, `editReminder`, `removeReminder`, `getReminder`, `getListReminder`, `getReminderResponses`.
- Ghi chú/bảng: `createNote`, `editNote`, `getListBoard`, `getFriendBoardList`.

### Cài đặt tài khoản và hộp thư

Còn chưa khai thác:

- Ghim/ẩn/lưu trữ/chưa đọc: `setPinnedConversations`, `getPinConversations`, `setHiddenConversations`, `getHiddenConversations`, `getArchivedChatList`, `updateArchivedChatList`, `addUnreadMark`, `removeUnreadMark`.
- Nhãn Zalo thật: `getLabels`, `updateLabels`.
- Im lặng: `setMute`, `getMute`.
- Hồ sơ: `updateProfile`, `updateProfileBio`, `changeAccountAvatar`, `deleteAvatar`, `reuseAvatar`, `getAvatarList`.
- Tự xóa chat: `updateAutoDeleteChat`, `getAutoDeleteChat`.

### Quick message, auto reply và ZBusiness

Còn chưa khai thác:

- Quick message Zalo: `addQuickMessage`, `updateQuickMessage`, `removeQuickMessage`, `getQuickMessageList`.
- Auto reply Zalo: `createAutoReply`, `updateAutoReply`, `deleteAutoReply`, `getAutoReplyList`.
- ZBusiness: `getBizAccount`, catalog, product catalog, upload product photo.

## 4. Nhóm ý tưởng nên triển khai

### 4.1. Inbox vận hành chuyên nghiệp

1. Trạng thái đã nhận, đã xem, đang gõ

- Dùng `seen_messages`, `delivered_messages`, `typing`, `sendTypingEvent`.
- Giá trị: nhân viên biết khách đã đọc hay chưa, tránh gửi lặp; trải nghiệm giống app chat thật hơn.
- MVP: hiển thị tick đã nhận/đã xem ở tin outbound, dòng "khách đang soạn..." trong header hội thoại.
- Rủi ro: payload sự kiện có thể khác giữa chat 1-1 và nhóm, cần lưu event thô để debug.

2. Hộp thư theo trạng thái xử lý

- Thêm trạng thái nội bộ cho hội thoại: mới, đang xử lý, chờ khách, đã hẹn, đã chốt, cần gọi lại, khiếu nại, đóng.
- Tận dụng bảng `zalo_conversations` và tag hiện có.
- Giá trị: biến danh sách chat thành pipeline chăm sóc khách.
- MVP: filter nhanh theo trạng thái, nút đổi trạng thái ngay trên header chat, lưu lịch sử thay đổi.

3. Phân công hội thoại cho nhân viên

- Thêm `assigned_user_id`, `assigned_at`, `assigned_by` cho hội thoại.
- Giá trị: đội nhiều người tránh trả lời trùng, quản lý biết ai chịu trách nhiệm.
- MVP: admin giao hội thoại, nhân viên chỉ thấy "của tôi" và "chưa giao" theo quyền.
- Mở rộng: tự giao theo tài khoản Zalo, tag, chi nhánh, ca trực hoặc round-robin.

4. SLA và cảnh báo khách chờ lâu

- Tính từ `last_message_at`, `last_message_direction`, `unread_count`.
- Giá trị: giảm mất khách vì bỏ sót tin.
- MVP: badge "quá 5 phút", "quá 15 phút", sort theo mức khẩn.
- Mở rộng: cảnh báo qua email/webhook khi hội thoại VIP hoặc khiếu nại bị trễ.

5. Ghi chú nội bộ và lịch sử bàn giao

- Ghi chú không gửi sang Zalo, gắn với hội thoại.
- Giá trị: nhân viên sau đọc được bối cảnh mà không phải hỏi lại khách.
- MVP: tab "Ghi chú" ở panel phải, có người tạo và thời gian.
- Mở rộng: mention nhân viên, checklist bàn giao cuối ca.

6. Saved views cho từng vai trò

- Ví dụ: "Chưa đọc", "VIP chờ xử lý", "Khách mới hôm nay", "Khiếu nại", "Của tôi", "Tài khoản lỗi".
- Giá trị: giảm thao tác lọc thủ công.
- MVP: bộ lọc lưu sẵn theo tag, tài khoản, người phụ trách, trạng thái, thời gian.

### 4.2. CRM nhẹ ngay trong Zalo

1. Hồ sơ khách hàng hợp nhất

- Gộp thông tin từ nhiều tài khoản Zalo nếu cùng số điện thoại hoặc cùng Zalo UID.
- Trường nên có: tên hệ thống, tên Zalo, số điện thoại, chi nhánh, nguồn, nhu cầu, lần tương tác cuối, tag, ghi chú.
- Giá trị: một khách nhắn nhiều nick vẫn nhận diện được.
- MVP: bảng `customers`, liên kết `zalo_contacts` và `zalo_conversations`.

2. Pipeline bán hàng/chăm sóc

- Các giai đoạn: lead mới, đã tư vấn, chờ lịch, đã đặt lịch, đã đến, chăm sóc sau dịch vụ, tái mua, mất liên hệ.
- Giá trị: báo cáo chuyển đổi theo hội thoại Zalo.
- MVP: kanban đơn giản dựa trên trạng thái hội thoại, kéo thả chuyển giai đoạn.

3. Lịch hẹn và nhắc chăm sóc

- Cho phép tạo lịch hẹn từ hội thoại, lưu ngày giờ, cơ sở, dịch vụ, người phụ trách.
- Có thể tận dụng `createReminder` của Zalo cho nhắc trong nhóm hoặc dùng scheduler nội bộ cho chắc.
- Giá trị: biến chat thành hành động cụ thể.
- MVP: reminder nội bộ trước, gửi mẫu nhắc lịch thủ công.
- Mở rộng: tự gửi nhắc lịch qua Zalo theo kịch bản đã duyệt.

4. Import lead theo số điện thoại

- Dùng `findUser`, `getMultiUsersByPhones`, `sendFriendRequest`.
- Giá trị: đưa danh sách khách từ CRM/Excel vào quy trình kết bạn.
- MVP: upload CSV, kiểm tra số tìm được, cho nhân viên duyệt từng batch trước khi gửi lời mời.
- Rủi ro: dễ bị xem là spam, bắt buộc giới hạn số lượng/ngày/tài khoản và có nội dung cá nhân hóa.

5. Alias Zalo tự động

- Dùng `changeFriendAlias` để đặt tên gợi nhớ trên Zalo thật, ví dụ `KH - Nguyen Van A - HN - Botox`.
- Giá trị: đồng bộ ngược sang app Zalo, nhân viên dùng điện thoại vẫn nhận diện khách.
- MVP: nút "Đồng bộ tên gợi nhớ", có preview trước khi ghi sang Zalo.

### 4.3. AI Copilot và tự động hóa an toàn

1. AI gợi ý trả lời theo ngữ cảnh và tag

- Hệ thống đã có AI agent và lịch sử tin nhắn.
- Bổ sung dữ liệu vào prompt: tag, trạng thái pipeline, ghi chú nội bộ, mẫu phù hợp, thông tin chi nhánh/dịch vụ.
- Giá trị: câu trả lời sát nghiệp vụ hơn so với chỉ đọc đoạn chat.
- MVP: panel gợi ý 2 đến 3 phương án trả lời, nhân viên bấm chèn.

2. AI phân loại hội thoại tự động

- Khi có tin đến, AI gán nhãn: hỏi giá, đặt lịch, khiếu nại, spam, hỏi ngoài phạm vi, cần người thật.
- Giá trị: tự ưu tiên hội thoại và giảm thao tác gắn thẻ.
- MVP: chạy nền cho tin inbound mới, chỉ gợi ý tag trước, chưa tự gắn khi độ tin cậy thấp.

3. AI tóm tắt hội thoại

- Tạo summary ngắn: khách cần gì, đã hứa gì, bước tiếp theo.
- Giá trị: bàn giao ca nhanh và mở chat cũ không phải đọc lại hàng trăm tin.
- MVP: summary cập nhật mỗi khi hội thoại có 5 đến 10 tin mới hoặc khi nhân viên bấm "Tóm tắt".

4. Guardrails trước khi gửi

- Kiểm tra nội dung có số tiền, cam kết kết quả, thông tin nhạy cảm, từ khóa khiếu nại, hoặc lệch chính sách.
- Giá trị: giảm lỗi tư vấn và rủi ro pháp lý.
- MVP: cảnh báo trước khi gửi, chưa chặn cứng.
- Mở rộng: chặn AI tự gửi trong các case khiếu nại, hoàn tiền, y tế, pháp lý, OTP.

5. Agent theo kịch bản nhiều bước

- Ví dụ: hỏi nhu cầu, hỏi chi nhánh, hỏi ngày giờ, xác nhận thông tin, chuyển nhân viên.
- Giá trị: AI không trả lời rời rạc, mà dẫn khách đến hành động.
- MVP: cấu hình flow dạng state machine đơn giản theo hội thoại.

6. Học từ tin nhắn mẫu và câu trả lời tốt

- Dùng message templates hiện có làm knowledge base nhẹ.
- Cho phép đánh dấu một câu trả lời là "mẫu tốt" để AI học phong cách.
- MVP: tìm mẫu gần nhất theo từ khóa/tag và đưa vào prompt.

7. AI tự gửi theo điều kiện hẹp

- Chỉ tự gửi khi hội thoại thuộc nhóm an toàn: hỏi giờ mở cửa, địa chỉ, bảng giá tham khảo, xác nhận đã nhận thông tin.
- Không tự gửi khi có khiếu nại, giá trị cao, yêu cầu y tế/pháp lý/tài chính, khách tức giận.
- MVP: rule engine trước AI, sau đó AI soạn và kiểm tra qua guardrails.

### 4.4. Tin nhắn mẫu và thư viện nội dung

1. Template có biến

- Ví dụ: `{ten_khach}`, `{chi_nhanh}`, `{ngay_hen}`, `{gio_hen}`, `{nhan_vien}`, `{dich_vu}`.
- Giá trị: giảm sửa tay và giảm gửi nhầm.
- MVP: chèn biến vào ô soạn, biến thiếu thì highlight để nhân viên điền.

2. Template theo tag/trạng thái

- Khi hội thoại có tag "khách lỡ hẹn", ưu tiên mẫu nhắc lịch; tag "VIP" ưu tiên giọng chăm sóc riêng.
- Giá trị: danh sách mẫu ngắn và đúng ngữ cảnh.

3. Phê duyệt template

- Nhân viên đề xuất mẫu, admin duyệt trước khi dùng chung.
- Giá trị: kiểm soát chất lượng nội dung.

4. Quick message đồng bộ với Zalo

- Dùng `getQuickMessageList`, `addQuickMessage`, `updateQuickMessage`.
- Giá trị: nhân viên dùng app Zalo thật vẫn có bộ trả lời nhanh.
- Rủi ro: có thể xung đột với mẫu nội bộ, cần quy ước nguồn sự thật.

### 4.5. Quản lý bạn bè, chống spam và chất lượng danh bạ

1. Quản lý lời mời đã gửi

- Dùng `getSentFriendRequest`, `getFriendRequestStatus`.
- Giá trị: biết số lời mời pending, tránh gửi lặp.
- MVP: tab "Đã gửi", trạng thái pending/accepted/rejected/expired.

2. Chặn/bỏ chặn người dùng

- Dùng `blockUser`, `unblockUser`.
- Giá trị: xử lý spam, quấy rối, nội dung độc hại.
- MVP: nút "Chặn" trong hồ sơ khách, bắt nhập lý do, log audit.

3. Kiểm tra online/last online để ưu tiên

- Dùng `getFriendOnlines`, `lastOnline`.
- Giá trị: gọi lại hoặc nhắn lại đúng thời điểm.
- Rủi ro: nhạy cảm về quyền riêng tư, nên chỉ dùng như tín hiệu phụ và không hiển thị quá lộ.

4. Dọn danh bạ chất lượng thấp

- Gợi ý xóa bạn hoặc lưu trữ nếu lâu không tương tác, không có tag quan trọng.
- Không tự động xóa, chỉ gợi ý cho admin.

### 4.6. Nhóm Zalo và cộng đồng khách hàng

1. Duyệt thành viên nhóm

- Dùng `getPendingGroupMembers`, `reviewPendingMemberRequest`.
- Giá trị: quản lý nhóm khách hàng, lớp học, cộng đồng, chiến dịch.
- MVP: tab "Chờ duyệt" trong panel nhóm.

2. Quản lý vai trò nhóm

- Dùng `addGroupDeputy`, `removeGroupDeputy`, `changeGroupOwner`.
- Giá trị: bàn giao nhóm cho nhân viên phụ trách.
- Cần kiểm tra quyền Zalo trước khi hiện nút.

3. Link mời nhóm

- Dùng `enableGroupLink`, `disableGroupLink`, `getGroupLinkInfo`.
- Giá trị: tạo link tham gia nhóm cho chiến dịch, có thể tắt khi hết hạn.
- MVP: tạo/tắt link, copy link, log người thao tác.

4. Poll nhóm

- Dùng `createPoll`, `addPollOptions`, `votePoll`, `lockPoll`, `getPollDetail`.
- Giá trị: khảo sát lịch học, chọn khung giờ, vote dịch vụ quan tâm.
- MVP: tạo poll từ UI, xem kết quả trong hội thoại.

5. Reminder nhóm

- Dùng `createReminder`, `editReminder`, `removeReminder`, `getListReminder`.
- Giá trị: nhắc lịch live, lịch hẹn nhóm, deadline thanh toán.
- MVP: nhắc việc nội bộ trước, sau đó mới nhắc trực tiếp trong nhóm Zalo.

6. Note/board nhóm

- Dùng `createNote`, `editNote`, `getListBoard`.
- Giá trị: ghim nội dung hướng dẫn, lịch trình, chính sách trong nhóm.
- Chỉ nên làm khi sản phẩm có use case cộng đồng/nhóm rõ.

### 4.7. Bán hàng, Zalo OA và ZBusiness

1. ZBS Template Message và chính sách gửi tin OA

- Tách hẳn tin tư vấn trong cửa sổ hội thoại khỏi tin giao dịch/hậu mãi/truyền thông theo
  chuẩn Zalo Business Solution.
- MVP: quản lý template, biến số, trạng thái duyệt, quota, chi phí dự kiến, lịch sử gửi,
  lỗi và trạng thái delivery. Không cho dùng campaign cá nhân để giả lập broadcast OA.
- Giá trị: mở được use case xác nhận đơn, nhắc lịch, hậu mãi và chăm sóc ngoài cửa sổ chat;
  đồng thời giảm rủi ro gửi sai loại tin.
- Tham chiếu: [Zalo Developers](https://developers.zalo.me/docs) và [bảng giá/tính năng
  OA](https://zalo.solutions/oa/pricing).

2. Đồng bộ Chatbot native của OA

- Đồng bộ hoặc hiển thị liên kết tới menu, flow, rule, form, tag và dynamic API của Zalo OA.
- Không cần clone toàn bộ trình dựng chatbot ở phase đầu; FlyChat nên nhận lead/form, gắn
  customer, chuyển người phụ trách và đưa kết quả vào pipeline.
- Giá trị: tận dụng năng lực chính thức của Zalo nhưng vẫn giữ CRM, AI và báo cáo tập trung.

3. Catalog sản phẩm/dịch vụ

- Dùng `getBizAccount`, `createCatalog`, `createProductCatalog`, `uploadProductPhoto`.
- Giá trị: gửi thông tin sản phẩm/dịch vụ chuẩn hơn, nhất quán hơn.
- Điều kiện: tài khoản phải có năng lực ZBusiness, cần kiểm tra trước khi bật UI.

4. Gợi ý sản phẩm theo hội thoại

- AI đọc nhu cầu và đề xuất catalog phù hợp cho nhân viên chèn vào tin.
- MVP: chỉ gợi ý nội bộ, nhân viên bấm gửi.

5. Báo cáo hiệu quả theo dịch vụ

- Dựa vào tag/pipeline/template/catalog được gửi.
- Chỉ đo được chuyển đổi nội bộ nếu có trạng thái "đã chốt" hoặc tích hợp CRM/booking.

### 4.8. Tích hợp và nền tảng mở

1. Webhook outbound

- Khi có tin mới, tag mới, trạng thái pipeline đổi, lịch hẹn tạo, AI trả lời, gửi webhook ra CRM/n8n.
- Giá trị: kết nối hệ sinh thái mà không phải xây tất cả trong FlyChat.
- MVP: cấu hình URL, secret, event types, retry log, chữ ký HMAC, idempotency key và nút replay
  event lỗi. Không gửi webhook đồng bộ trong request nhận tin.

2. API inbound cho CRM

- Cho CRM tạo hội thoại, gửi tin qua Zalo, gắn tag, tạo lịch nhắc.
- Hệ thống đã có OAuth/external API nên có nền.
- Cần rate limit theo token và theo tài khoản Zalo.

3. Đồng bộ khách hàng với CRM/booking

- Mapping khách theo phone/Zalo UID.
- Khi khách đặt lịch trong CRM, FlyChat tự hiện lịch trong sidebar.
- Khi nhân viên chốt trong FlyChat, đẩy trạng thái về CRM.
- Nên bắt đầu bằng một connector mẫu cho Google Calendar/booking hoặc một API generic; chưa
  cần xây CRM đầy đủ ngay.

4. Automation builder đơn giản

- Trigger: tin mới, tag được gắn, khách chưa phản hồi sau N giờ, lịch hẹn sắp tới.
- Action: gắn tag, tạo task, gửi mẫu, gọi webhook, chuyển nhân viên, bật/tắt AI.
- MVP: rule dạng form, chưa cần canvas phức tạp.

### 4.9. Giám sát, an toàn và vận hành nhiều tài khoản

1. Health dashboard cho tài khoản Zalo

- Hiện đã có health alert cơ bản khi đăng nhập và trạng thái READY, DISCONNECTED,
  RELOGIN_REQUIRED, ERROR; phần dashboard chi tiết vẫn còn thiếu.
- Bản tiếp theo nên hiển thị lần nhận tin cuối, token OA, reconnect, queue, lỗi gần nhất và
  số tin gửi/lỗi theo từng tài khoản. Giá trị: vận hành nhiều tài khoản không bị mù trạng thái.

2. Cảnh báo phiên bất thường

- Cảnh báo khi tài khoản rớt quá N lần, không nhận tin quá lâu, cần quét QR, queue callback tăng.
- Gửi qua email/webhook hoặc một kênh nội bộ.

3. Rate limit gửi tin theo tài khoản

- Campaign hiện đã có delay, queue, pause/cancel, retry và giới hạn riêng cho OA. Còn thiếu
  token-bucket dùng chung cho mọi đường gửi (chat tay, AI, API, campaign), quota theo tenant,
  suppression list và nút dừng toàn hệ thống.
- Bắt buộc trước khi mở import lead hoặc tự động kết bạn.

4. Audit log thao tác nhạy cảm

- Log: gửi tin, thu hồi, xóa, chặn, xóa bạn, tạo nhóm, đá thành viên, bật AI tự gửi, đổi prompt, chuyển chủ sở hữu tài khoản.
- Giá trị: truy vết khi có sự cố.

5. Consent và suppression center

- Lưu nguồn đồng ý, thời điểm, mục đích, kênh, trạng thái opt-in/opt-out và lý do chặn liên hệ.
- Mọi campaign, auto-reply follow-up, import lead và ZBS broadcast phải kiểm tra danh sách
  này trước khi gửi.
- Đây là khoảng trống quan trọng khi so với các sản phẩm marketing/CRM chuyên nghiệp; không
  nên chỉ dựa vào tag để suy ra khách được phép nhận tin.

6. Kho lưu sự kiện thô

- Lưu một phần payload `worker/events` có TTL để debug `zca-js` khi Zalo đổi cấu trúc.
- Không lưu vô hạn, tránh phình DB và rủi ro dữ liệu nhạy cảm.

7. Chính sách dữ liệu và xóa mềm

- Với hội thoại/tin nhắn quan trọng, hạn chế xóa cứng.
- Xóa hội thoại khỏi hệ thống nên có soft delete hoặc archive để giảm mất dữ liệu không tái tạo được.

## 5. Ưu tiên triển khai cập nhật

### Đợt 1: Inbox control và trust layer — ưu tiên cao nhất

Mục tiêu: biến inbox hiện tại thành nơi vận hành đội nhóm; không phụ thuộc nhiều vào endpoint
Zalo mới.

| Tính năng | Giá trị | Công sức | Rủi ro | Gợi ý kỹ thuật | Trạng thái |
|---|---:|---:|---:|---|---|
| Trạng thái đã nhận/đã xem/đang gõ | Cao | Trung bình | Trung bình | Listener `seen_messages`, `delivered_messages`, `typing`; receipt theo message/thread | ⏳ |
| Phân công hội thoại | Cao | Trung bình | Thấp | `assigned_user_id`, lịch sử giao nhận, filter “của tôi/chưa giao” | ⏳ |
| SLA theo chính sách | Cao | Trung bình | Thấp | Giờ làm việc, `sla_due_at`, cảnh báo, pause khi chờ khách; báo cáo hiện tại mới là suy luận | ⏳ |
| Ghi chú nội bộ và bàn giao | Cao | Thấp | Thấp | `conversation_notes`, mention, checklist cuối ca, timeline nội bộ | ⏳ |
| Template có biến | Cao | Trung bình | Thấp | Parser/validator biến; template hiện có nhưng chưa có context khách để điền tự động | 🟡 |
| AI tóm tắt hội thoại | Cao | Trung bình | Thấp | Đã có summary thủ công lưu theo conversation; tiếp theo là cập nhật async và next action | ✅/🟡 |
| Health dashboard tài khoản | Cao | Trung bình | Thấp | Đã có health alert; bổ sung last event, token OA, queue, reconnect, error rate | 🟡 |

Đây là nhóm nên làm trước vì tạo khác biệt vận hành rõ nhất và tận dụng được schema/UI hiện có.

### Đợt 2: CRM và AI vận hành

Mục tiêu: biến hội thoại thành quy trình bán hàng/chăm sóc.

| Tính năng | Giá trị | Công sức | Rủi ro | Gợi ý kỹ thuật | Trạng thái |
|---|---:|---:|---:|---|---|
| Hồ sơ khách hàng hợp nhất | Rất cao | Cao | Thấp | `customers` + identity theo phone/Zalo UID + custom fields/consent | ⏳ |
| Pipeline hội thoại | Rất cao | Trung bình | Thấp | Status, priority, kanban, saved views; không dùng tag thay status | ⏳ |
| Lịch hẹn/nhắc chăm sóc | Cao | Trung bình | Thấp | Scheduler nội bộ trước; connector Calendar/booking sau | ⏳ |
| AI phân loại intent/tag/sentiment | Cao | Trung bình | Thấp | Job async, confidence threshold, nhân viên duyệt kết quả | ⏳ |
| Guardrails trước khi gửi | Cao | Trung bình | Thấp | Policy/rule + classifier, chặn case nhạy cảm, lưu quyết định | ⏳ |
| Knowledge base/RAG có duyệt | Cao | Trung bình | Thấp | Tài liệu theo đơn vị, version, nguồn trích dẫn, test trước publish | ⏳ |
| Webhook outbound | Cao | Trung bình | Thấp | Event log, HMAC, retry/backoff, idempotency, replay | ⏳ |

Đợt này tạo lợi thế rõ nhất cho sale/care: hội thoại phải dẫn đến hành động, không chỉ tạo ra câu trả lời.

### Đợt 3: Khai thác sâu Zalo

Mục tiêu: tận dụng các năng lực Zalo thật mà đối thủ inbox thường thiếu.

| Tính năng | Giá trị | Công sức | Rủi ro | Gợi ý kỹ thuật | Trạng thái |
|---|---:|---:|---:|---|---|
| Quản lý lời mời đã gửi | Trung bình | Trung bình | Trung bình | `getSentFriendRequest`, `getFriendRequestStatus`, chống gửi lặp | ⏳ |
| Import lead theo số điện thoại | Cao | Trung bình | Cao | CSV, dedupe, preview, opt-in/suppression, batch nhỏ, rate limit | ⏳ |
| Alias Zalo tự động | Trung bình | Thấp | Trung bình | `changeFriendAlias`, preview và rollback/log | ⏳ |
| Chặn/bỏ chặn user | Trung bình | Thấp | Trung bình | Audit log, block nội bộ và đồng bộ với suppression list | ⏳ |
| Duyệt thành viên nhóm | Trung bình | Trung bình | Trung bình | `getPendingGroupMembers`, `reviewPendingMemberRequest` | ⏳ |
| Link mời nhóm | Trung bình | Trung bình | Trung bình | Enable/disable link, log thao tác, expiry | ⏳ |

Nhóm này nên bật theo cấu hình tenant hoặc role, vì thao tác ghi trực tiếp sang Zalo có rủi ro vận hành.

### Đợt 4: Công cụ nhóm, campaign, ZBusiness

Mục tiêu: mở rộng sang cộng đồng, bán hàng và tự động hóa nâng cao.

| Tính năng | Giá trị | Công sức | Rủi ro | Gợi ý kỹ thuật | Trạng thái |
|---|---:|---:|---:|---|---|
| Poll nhóm | Trung bình | Trung bình | Trung bình | Chỉ hiện trong chat nhóm | ⏳ |
| Reminder nhóm | Trung bình | Trung bình | Trung bình | Bắt đầu bằng reminder nội bộ | ⏳ |
| Board/note nhóm | Trung bình | Trung bình | Trung bình | Chỉ làm khi có use case cộng đồng rõ | ⏳ |
| Catalog ZBusiness | Cao nếu có ZBusiness | Cao | Trung bình | Kiểm tra `getBizAccount`, bật theo capability | ⏳ |
| Automation builder | Rất cao | Cao | Cao | AI flow hiện có; bổ sung trigger/action generic và execution log | 🟡 |
| Campaign cá nhân/OA có kiểm soát | Cao | Cao | Rất cao | Đã có queue/filter/pause/rate limit; tiếp theo là consent, suppression, ROI | 🟡 |
| Broadcast/ZBS chính thức | Cao | Cao | Trung bình | Module riêng, template approval/quota/cost/delivery; không trộn campaign tự do | ⏳ |

Campaign hàng loạt có nhu cầu nhưng rủi ro cao nhất. Phần hiện có nên được giữ như công cụ
outbound có kiểm soát; chỉ mở rộng sau khi có opt-in, suppression, quota theo tenant, audit
và nút dừng khẩn cấp. Broadcast/ZBS chính thức là một sản phẩm con khác.

## 6. Các ý tưởng chi tiết có thể đưa vào backlog

### Backlog UI/UX chat

- Sidebar hội thoại có tab: Tất cả, Chưa đọc, Của tôi, Chờ khách, Quá SLA, VIP, Khiếu nại.
- Header hội thoại có trạng thái phiên, người phụ trách, pipeline status, last seen, typing.
- Panel phải cho hồ sơ khách, ghi chú, lịch hẹn, tag, summary AI.
- Composer có quote, template variables, preview file, cảnh báo nội dung nhạy cảm.
- Menu tin nhắn có: trả lời, chuyển tiếp, copy, thu hồi, xóa phía tôi, tạo template từ tin này, tạo ghi chú từ tin này.
- Timeline nội bộ xen kẽ với tin nhắn: đổi trạng thái, gắn tag, bàn giao, AI tự gửi, lịch hẹn.

### Backlog dữ liệu và báo cáo

- Báo cáo số hội thoại mới theo ngày/tài khoản/nhân viên.
- Thời gian phản hồi đầu tiên và trung bình.
- Tỷ lệ quá SLA.
- Số hội thoại đã chốt theo tag/trạng thái.
- Hiệu quả template: mẫu nào được dùng nhiều, mẫu nào dẫn đến phản hồi tốt.
- Hiệu quả AI: số lần tạo nháp, tỷ lệ nhân viên dùng nguyên văn, số lần bị chỉnh sửa, số lần tự gửi bị tắt.
- Sức khỏe tài khoản: uptime, số lần reconnect, số tin gửi/nhận, lỗi gửi.

### Backlog AI

- Tóm tắt hội thoại theo định dạng chuẩn: nhu cầu, thông tin đã có, thiếu gì, bước tiếp theo.
- Phát hiện intent: hỏi giá, đặt lịch, đổi lịch, khiếu nại, hỏi địa chỉ, spam, tuyển dụng, ngoài phạm vi.
- Gợi ý tag và pipeline status.
- Gợi ý template phù hợp.
- Gợi ý câu hỏi tiếp theo để chốt lịch.
- Cảnh báo khi nhân viên sắp gửi nội dung có rủi ro.
- Sinh câu trả lời theo tone thương hiệu.
- Auto-reply theo khung giờ ngoài giờ làm việc.
- Auto-reply khi khách nhắn lần đầu.
- Auto-reply follow-up nếu khách chưa trả lời sau N giờ, nhưng phải có opt-in và giới hạn.

### Backlog nhóm Zalo

- Quản lý thành viên nhóm với tìm kiếm, role, trạng thái chờ duyệt.
- Gắn nhóm với một chiến dịch hoặc lớp/chương trình.
- Tạo poll từ mẫu.
- Tạo reminder nhóm cho lịch live, lịch học, lịch hẹn.
- Quản lý link mời nhóm và lịch sử bật/tắt.
- Cảnh báo khi nhóm đổi tên/avatar/thành viên bất thường.

### Backlog danh bạ và lead

- Tìm user theo số điện thoại trước khi kết bạn.
- Import CSV lead, validate số, loại trùng, phân bổ theo tài khoản Zalo.
- Theo dõi lời mời đã gửi và tự nhắc hủy lời mời cũ.
- Đồng bộ alias Zalo từ CRM.
- Chặn user spam, có danh sách block nội bộ.
- Gợi ý gộp khách nếu nhiều hội thoại cùng số điện thoại.

### Backlog tích hợp

- Webhook event: message.created, conversation.assigned, tag.changed, appointment.created, ai.reply.sent, account.status.changed.
- API gửi tin từ CRM với idempotency key.
- API tra lịch sử hội thoại theo khách.
- OAuth scope chi tiết: đọc hội thoại, gửi tin, quản lý tag, quản lý tài khoản.
- n8n/Zapier style recipes: tin mới tạo lead, tag VIP tạo task, lịch hẹn gửi Google Calendar.

## 7. Gợi ý kiến trúc cho các tính năng mới

### Luồng realtime event

Nên chuẩn hóa toàn bộ event từ worker vào một bảng hoặc service trung gian:

- `account_id`
- `thread_id`
- `thread_type`
- `event_type`
- `payload`
- `occurred_at`
- `processed_at`
- `status`

Lợi ích:

- Dễ replay khi logic ingest lỗi.
- Dễ debug khi `zca-js` hoặc Zalo đổi payload.
- Dễ mở rộng cho seen, delivered, typing, group pending, old reactions.

### Lưu trạng thái đọc/nhận

Đề xuất thêm vào `zalo_messages` hoặc bảng riêng:

- `delivered_at`
- `seen_at`
- `seen_by`
- `delivery_payload`

Với nhóm, một tin có thể có nhiều người xem/nhận, nên bảng riêng sẽ linh hoạt hơn:

- `zalo_message_receipts`
- `zalo_message_id`
- `actor_id`
- `type`: delivered/seen
- `occurred_at`

### Assignment và SLA

Đề xuất thêm vào `zalo_conversations`:

- `assigned_user_id`
- `assigned_at`
- `assigned_by`
- `status`
- `priority`
- `sla_due_at`
- `closed_at`

Và bảng lịch sử:

- `conversation_activity_logs`
- `conversation_id`
- `actor_user_id`
- `type`
- `before`
- `after`
- `created_at`

### Customer profile

Đề xuất mô hình:

- `customers`: thông tin khách ở cấp sản phẩm.
- `customer_zalo_identities`: map customer với `zalo_account_id`, `zalo_uid`, phone, display name.
- `customer_notes`: ghi chú cấp khách, không chỉ cấp hội thoại.
- `appointments`: lịch hẹn, trạng thái, chi nhánh, dịch vụ, người phụ trách.

### AI pipeline

Nên tách AI thành các job nhỏ:

- `ClassifyConversationJob`: intent, sentiment, suggested tags.
- `SummarizeConversationJob`: summary và next action.
- `GenerateReplyJob`: tạo nháp hoặc tự gửi.
- `SafetyCheckJob`: kiểm tra nội dung trước gửi.

Mỗi job cần lưu:

- model/provider
- prompt version
- input hash
- output
- confidence
- decision
- latency/cost nếu có

## 8. Những tính năng không nên ưu tiên ngay

Không nên làm sớm nếu chưa có nghiệp vụ rõ:

- Broadcast/campaign gửi hàng loạt không kiểm soát. Rủi ro khóa tài khoản cao.
- Tự động kết bạn số lượng lớn. Rủi ro spam cao.
- Cài đặt sâu tài khoản Zalo như đổi avatar, bio, language, active status nếu không phục vụ quy trình vận hành.
- Disperse group, change owner, leave group. Đây là thao tác phá hủy hoặc rủi ro cao, cần quyền rất chặt.
- Dùng `custom` để gọi endpoint Zalo chưa được thư viện hóa nếu chưa có test thực tế và fallback.
- Lưu toàn bộ event thô vô hạn. Có thể phình DB và chứa dữ liệu nhạy cảm.

## 9. MVP tiếp theo đề xuất trong 4–6 tuần

Không đưa AI summary, AI flow, health alert, OA hay campaign vào kế hoạch như tính năng mới
nữa; đó là nền đã có. MVP tiếp theo nên là một “workspace xử lý khách” hoàn chỉnh.

### Sprint 1: Conversation workspace — P0

- Thêm `status` (`open`, `pending_customer`, `resolved`, `snoozed`), `priority`,
  `assigned_user_id`, `assigned_at`, `assigned_by`, `closed_at` vào `zalo_conversations`.
- Tạo `conversation_notes` và `conversation_activity_logs`; mọi lần giao người, đổi trạng
  thái, gắn tag, bật/tắt AI phải tạo timeline nội bộ.
- UI có bộ lọc: “Của tôi”, “Chưa giao”, “Chờ khách”, “Quá SLA”, “Đã đóng”, “VIP/khiếu nại”.
- Chống trả lời trùng: hiển thị người đang xử lý, cảnh báo khi một hội thoại vừa được nhân
  viên khác gửi tin.

**Tiêu chí nghiệm thu:** hai nhân viên không thể âm thầm cùng nhận một hội thoại; admin xem
được ai giao cho ai và khi nào; refresh/poll không làm mất assignment hoặc trạng thái.

### Sprint 2: SLA và notification — P0

- Cấu hình giờ làm việc/ngày nghỉ theo đơn vị, SLA theo tag hoặc priority, `sla_due_at`.
- Tách rõ ba khái niệm: “chưa đọc”, “đang chờ phản hồi từ nhân viên”, “đang chờ khách”.
- Notification trong app trước; email/webhook sau. Có escalation khi quá SLA 5/15/30 phút.
- Giữ báo cáo hiện tại nhưng bổ sung metric thật: first response, resolution time, reopen rate,
  backlog theo người phụ trách.

**Tiêu chí nghiệm thu:** một hội thoại chờ khách không bị tính vào backlog nhân viên; đổi giờ
làm việc không làm sai dữ liệu lịch sử; dashboard và danh sách dùng cùng một rule SLA.

### Sprint 3: Customer + appointment — P0/P1

- Thêm `customers`, `customer_zalo_identities`, `customer_consents`, `customer_notes`,
  `appointments` và trường tùy biến theo đơn vị.
- Quy tắc gộp an toàn: ưu tiên `zalo_account_id + thread_id`, sau đó UID; chỉ gộp theo số điện
  thoại khi có xác nhận hoặc độ tin cậy đủ cao, không gộp chỉ vì trùng tên.
- Từ hội thoại tạo lead, cập nhật pipeline, tạo lịch hẹn, giao nhân viên và đặt reminder nội
  bộ. Giai đoạn đầu không tự gửi lời nhắc qua Zalo.
- Panel phải hiển thị hồ sơ, nguồn lead, lần tương tác cuối, lịch hẹn, task và lịch sử thay đổi.

**Tiêu chí nghiệm thu:** mở một khách có nhiều nick/hội thoại vẫn thấy đúng timeline; mỗi lịch
hẹn có trạng thái (`scheduled`, `confirmed`, `completed`, `cancelled`, `no_show`) và người phụ
trách; không gửi outbound nếu consent/suppression không cho phép.

### Sprint 4: AI copilot an toàn — P1

- Dùng summary/agent hiện có làm nền; bổ sung job phân loại intent, sentiment, tag đề xuất và
  “next best action”. Kết quả có confidence, model, prompt version và người duyệt.
- Tạo knowledge base theo đơn vị: tài liệu, phiên bản, trạng thái draft/published, nguồn trích
  dẫn; agent chỉ đọc bản published.
- Composer có AI draft 2–3 phương án, điền biến khách/lịch hẹn, kiểm tra chính sách trước khi
  gửi. Case khiếu nại, hoàn tiền, y tế/pháp lý, OTP hoặc cam kết kết quả phải chuyển người thật.
- Đo tỷ lệ dùng nguyên văn, tỷ lệ chỉnh sửa, tỷ lệ bị từ chối, chi phí/thời gian và kết quả sau
  gửi; không đánh giá AI chỉ bằng số tin đã gửi.

## 10. Thiết kế kỹ thuật nên chốt trước khi code

### 10.1. Luồng gửi tin thống nhất

Mọi đường gửi (chat tay, AI, API, campaign, OA) nên đi qua cùng một pipeline:

```text
draft -> permission -> consent/suppression -> quota/rate limit -> safety check
      -> outbox -> provider send -> receipt/webhook -> audit + metric
```

Các capability phải được trả theo tài khoản/kênh: `personal` và `oa` không dùng chung policy.
Không hiển thị nút hay gọi endpoint chỉ vì `zca-js` có method; phải kiểm tra capability, quyền
nhân viên, trạng thái phiên và giới hạn gửi trước.

### 10.2. Bảng nền tảng nên thêm

- `conversation_activity_logs`: assignment, status, tag, AI, campaign, handoff.
- `conversation_notes`: ghi chú nội bộ, mention, visibility, edited/deleted metadata.
- `customers`, `customer_zalo_identities`, `customer_consents`, `customer_custom_fields`.
- `appointments`, `tasks`: hành động tiếp theo và nhắc việc.
- `webhook_endpoints`, `webhook_deliveries`: HMAC, retry/backoff, response, replay, dead letter.
- `ai_suggestions`, `ai_safety_checks`, `knowledge_documents`, `knowledge_versions`.
- `message_receipts`: `delivered`, `seen`, actor, occurred time; với nhóm không nhét nhiều người
  xem vào một cột của `zalo_messages`.

### 10.3. Ranh giới OA và nick cá nhân

- OA: ưu tiên OpenAPI/Webhook chính thức; bổ sung ZBS Template Message, quota, chi phí, duyệt
  template, delivery và Chatbot/form native.
- Nick cá nhân: giữ `zca-js` ở vùng capability có test, delay, circuit breaker, kill switch và
  audit; không quảng bá campaign tự do hoặc tự động kết bạn hàng loạt như tính năng mặc định.
- Khi một khách xuất hiện ở cả OA và nick cá nhân, liên kết ở tầng `customer`, nhưng vẫn giữ
  riêng identity, consent, quota và lịch sử gửi theo kênh.

## 11. KPI sản phẩm nên đo

- Tỷ lệ hội thoại được phân công trong 1 phút và tỷ lệ hội thoại không có người phụ trách.
- First response time, resolution time, reopen rate, SLA hit rate và backlog cuối ca.
- Tỷ lệ hội thoại đi qua từng pipeline stage; số lịch hẹn, xác nhận, hoàn tất, no-show.
- Tỷ lệ khách có hồ sơ hợp nhất đúng; số bản ghi gộp nhầm phải được hoàn tác.
- Tỷ lệ dùng template, AI draft được chấp nhận/chỉnh sửa/từ chối; tỷ lệ AI tự gửi bị chặn.
- Tỷ lệ gửi thành công, lỗi theo nguyên nhân, quota đã dùng, số lần kill switch.
- Doanh thu hoặc giá trị lịch hẹn quy về nguồn/tag/campaign/template, nếu nghiệp vụ có dữ liệu.
- Uptime phiên, thời gian phát hiện mất kết nối, số lần quét QR lại và độ trễ webhook.

## 12. Các hướng sản phẩm có thể bán được

Thay vì mở rộng ngang ngay sang mọi kênh, nên chọn một vertical có quy trình lặp lại và dùng
FlyChat làm playbook:

1. **Spa/clinic:** lead → tư vấn dịch vụ → sàng lọc → đặt lịch → xác nhận → nhắc lịch → hậu mãi.
   Cần appointment, consent, template có biến, cảnh báo nội dung nhạy cảm và báo cáo no-show.
2. **Giáo dục/lớp học:** lead → tư vấn khóa → thu hồ sơ → vào nhóm → nhắc lịch → khảo sát/poll.
   Cần group workflow, form, reminder, phân lớp và lịch sử chăm sóc phụ huynh/học viên.
3. **Bất động sản:** lead → lọc nhu cầu → gán môi giới → gửi catalog → đặt lịch xem → follow-up.
   Cần routing theo khu vực, product/property catalog, task và attribution.
4. **Bán lẻ:** hỏi sản phẩm → gửi sản phẩm → chốt đơn → giao hàng → hậu mãi. Cần order context,
   product card, payment/ZBS và đồng bộ trạng thái đơn.

Khuyến nghị: chọn **một** vertical để làm bộ mẫu dữ liệu, agent prompt, template, pipeline và
dashboard hoàn chỉnh. Đây là cách kiểm chứng willingness-to-pay nhanh hơn việc xây CRM tổng quát.

## 13. Kết luận ưu tiên

Nếu chỉ chọn ba việc tiếp theo:

1. **Conversation workspace:** assignment, status, internal notes, SLA, notification và audit.
2. **Customer-to-action:** hồ sơ khách hợp nhất, consent, pipeline, appointment/task và attribution.
3. **OA growth có kiểm soát:** ZBS Template Message, quota/chi phí/delivery, đồng bộ Chatbot/form.

Sau đó mới đầu tư sâu vào RAG/AI action, connector CRM, mobile/PWA, poll/reminder nhóm và các
API danh bạ ít tạo doanh thu. Trục sản phẩm nên giữ vững: tính năng mới phải giúp xử lý nhanh
hơn, giảm bỏ sót, giảm gửi sai hoặc chứng minh được tác động đến lịch hẹn/doanh thu.