Tài liệu cho người quản trị

🔌 Hướng dẫn Agent API

⛔ LUẬT CỨNG: PHẢI CÓ PROXY MỚI DÙNG ĐƯỢC

Mỗi tài khoản Zalo bắt buộc phải được gán một proxy trước khi kết bạn hoặc gửi tin. Nick chưa có proxy bị chặn toàn bộ hai việc đó. Không có cách tắt luật này.

Vẫn quét QR đăng nhập được khi chưa có proxy, nhưng nick sẽ không làm được gì cho tới khi gán proxy. Đăng nhập được ≠ dùng được.

RỦI RO NẾU CHẠY KHÔNG PROXY: nick ra Internet bằng IP của máy chủ, dùng chung địa chỉ với mọi nick khác cũng chưa gán. Zalo thấy nhiều tài khoản cùng một IP là dấu hiệu rõ nhất của phần mềm chạy tự động → rất dễ bị KHOÁ TÀI KHOẢN, và khoá cả cụm.

Nguồn proxy khuyến nghị: proxiespool.com — phù hợp nhất với hệ thống này. Trần nick trên một proxy khác nhau theo hãng: mxhone….proxiespool.com = 1 nick/proxy · mxh….proxiespool.com = 3 nick/proxy · proxyno1.com = 10 nick/proxy. proxiespool bán hai gói, phân biệt bằng TÊN HOST: bắt đầu bằng mxhone là gói 1 nick, bắt đầu bằng mxh là gói 3 nick. Hệ thống chặn cứng ở mức này. Gán ở Tài Khoản Zalo → chip ⛔ Chưa có proxy.

Cấp quyền cho trợ lý AI (Codex / ChatGPT / Claude…) đọc & phân tích số liệu kết bạn của bạn để đưa ra khuyến nghị tối ưu.

1. Agent API là gì?

Là một "cổng" cho phép AI ngoài xem số liệu hệ thống kết bạn của bạn để phân tích và gợi ý tối ưu — ví dụ: nick nào chạy tốt/kém và vì sao, tệp data (segment) nào nên chạy / nên bỏ.

Giai đoạn 1 (hiện tại): CHỈ ĐỌC. AI xem số liệu và đưa khuyến nghị; bạn là người bấm áp trong app. AI không tự đổi được gì → rủi ro gần như bằng 0.

Giai đoạn 2 (đã có, mặc định KHÓA): bạn có thể bật quyền GHI để AI tự điều phối data / chỉnh cấu hình trong ngưỡng an toàn. Khi bật, hệ thống tự sao lưu DB trước (điểm khôi phục); mọi lệnh có dry-run (xem trước) + hoàn tác từng lệnh; AI vẫn KHÔNG đổi được chế độ nick / giới hạn tốc độ / xóa data.

📦 Sao lưu trước khi ghi: ở màn Agent API có nút "Sao lưu DB ngay", và bật quyền GHI sẽ tự backup. Panel "Nhật ký hành động — Hoàn tác" cho bạn xem mọi thay đổi agent đã làm và hoàn tác bất kỳ lệnh nào.

2. Cách dùng — 3 bước

Tạo API key ở màn 🔌 Agent API trong app: đặt tên (vd "Codex optimizer"), tích các quyền (GĐ1 nên chỉ tích 4 quyền đọc), bấm Tạo key. Hệ thống hiện key một lần duy nhất — copy ngay và lưu kỹ.

Nạp cho LLM: tải 2 file agent-api-reference.md (để AI biết gọi API gì) và agent-llm-instructions.md (dán làm "system prompt" để AI phân tích an toàn), rồi đưa key oak_live_… cho AI/tool để nó gọi https://app.zaloai.vn/api/agent/...

Nhận khuyến nghị từ AI → bạn xem và tự áp (đổi proxy, rót data, chỉnh giãn cách…) trong các màn app quen thuộc.

3. Quyền (scope) — nên cấp gì?

Giai đoạn 1 chỉ nên cấp 4 quyền ĐỌC:

Quyền	Cho phép AI
`campaign:read`	Đọc danh sách nick + nhật ký
`campaign:analyze`	Xếp hạng nick + phân tích "vì sao tốt"
`data:read`	Đọc kho số đã nạp (segment, số lượng)
`data:analyze`	Phễu chuyển đổi + chấm chất lượng data

Chưa cần cấp các quyền ghi (data:route, campaign:write…) cho tới khi bạn muốn AI tự tay điều phối (GĐ2).

4. An toàn — bạn kiểm soát hoàn toàn

Thu hồi tức thì: bấm "Thu hồi" là key chết ngay.
Công tắc an toàn (kill-switch): 1 công tắc tắt toàn bộ Agent API (hoặc chỉ khóa quyền ghi) tức thì.
Ghi vết: mọi lần AI gọi API đều được lưu (agent nào, gọi gì, lúc nào).
Không lộ mật khẩu: key lưu dạng mã hoá (hash), không lưu bản gốc.
Không phá được nick: kể cả GĐ2, AI không bật được chế độ READY, không tắt giới hạn tốc độ chống khóa, không xóa data (chỉ đánh dấu, hoàn tác được).

5. Ai cấp được key?

Chủ shop (OWNER) / Quản lý (ADMIN): cấp key cho tổ chức của mình (chỉ thấy nick + data của shop).
Super-admin: cấp key toàn hệ thống.

6. 📓 Báo cáo đăng Nhật ký từ điện thoại

Phần đăng Nhật ký (đăng bài lên trang cá nhân Zalo) chạy trên điện thoại thật do AI ngoài điều khiển. Khi AI đăng xong, nó tự báo về hệ thống để bạn theo dõi từng tài khoản.

Bật: cấp cho AI điện thoại một key có quyền post:report (nhóm "Đăng bài" khi tạo key). Quyền này không cần bật công tắc ghi.
Tự khớp đúng nick: AI chỉ gửi số điện thoại của tài khoản đã đăng — hệ thống tự gắn đúng tài khoản Zalo trên nền tảng (nhận cả 0932… lẫn +84932…) và lưu về đúng shop của bạn.
Xem ở đâu: menu "📓 Nhật ký đã đăng" — thấy từng tài khoản đã đăng gì, ngày/giờ, nội dung, ảnh, trạng thái. Tự cập nhật ~20 giây.

Tài liệu kỹ thuật để nạp cho AI điện thoại: post-report-api.md (tải ở màn Agent API).

7. Câu hỏi thường gặp

AI có gửi lời mời kết bạn hộ tôi không?
GĐ1: không. Nó chỉ phân tích + khuyến nghị. Việc gửi vẫn do worker của hệ thống (có giới hạn chống khóa) thực hiện khi bạn chạy chiến dịch.

Lỡ AI phân tích sai thì sao?
GĐ1 nó không đổi gì được, nên sai cũng vô hại — bạn chỉ đọc khuyến nghị rồi tự quyết.

Data số điện thoại của tôi có bị lộ?
Key chỉ thấy dữ liệu tổ chức của bạn, có ghi vết. Nên cấp quyền tối thiểu và thu hồi khi không dùng. Nếu đưa cho AI bên thứ ba, cân nhắc bật chế độ ẩn số điện thoại (GĐ2).

ZaloAI / OmniSell · Agent API — Hướng dẫn người dùng. Tài liệu kỹ thuật cho AI: account-api.md (kết bạn) · data-api.md (nạp lead) · post-report-api.md (báo cáo đăng Nhật ký).