claude-zalo-skills

Đây là bộ Claude Code skill để làm việc với Zalo. Bạn chỉ cần nhờ, Claude sẽ dẫn bạn qua từng thao tác trên Zalo for Developers rồi tự wire code — để bạn không phải một mình mò tài liệu Zalo hay ngồi dò lỗi -14003.

Zalo có vài "bẫy" ẩn khi tích hợp mà tài liệu ít nói tới: refresh_token xoay mỗi lần refresh (làm sai là chatbot chết sau khoảng 25h), redirect_uri phải khai đúng chỗ (sai sẽ ra -14003), và hai cơ chế OA rất dễ nhầm (bấm nhầm là hủy luôn liên kết của app khác). Những skill ở đây gói sẵn các bẫy đó thành quy trình chạy được.

Vì sao nên dùng skill, thay vì để AI tự mò?

Tài liệu Zalo không nói thẳng những bẫy trên, nên cách "hiển nhiên" mà cả người lẫn AI hay chọn thường lại là đường vòng tốn công. Khi thiếu tri thức đã kiểm chứng, trợ lý AI vẫn sẽ tự tin dẫn bạn đi — nghe rất hợp lý, nhưng có khi mất cả buổi mới nhận ra là sai đường.

Một ví dụ có thật lúc mình dựng repo này: để lấy OAuth token, hướng đi tự nhiên là triển khai xác thực domain thật rồi dựng hạ tầng redirect_uri (deploy meta-tag/file verify lên server, cấu hình HTTPS, xoay xở với lỗi -14003…). Đó đúng là hướng một trợ lý AI sẽ đề xuất nếu chưa biết mẹo. Nhưng đường đúng ngắn hơn nhiều: chỉ cần điền Callback Url ở Official Account → Thiết lập chung, Zalo sẽ tự sinh sẵn link cấp quyền — mở link đó là có code.

Skill này đã đi qua hết những khúc mò đó — cả cái đúng lẫn cái sai, những ngõ cụt và đúng thứ tự thao tác — rồi đúc lại thành các bước chạy thẳng. Nhờ vậy bạn (và trợ lý AI của bạn) không phải khám phá lại từ đầu.

Skills trong kho

Kho sẽ có thêm skill Zalo khác (webhook nhận tin, ZNS template, Zalo Login…).

Cài đặt

Là plugin Claude Code — repo này là một marketplace tự host:

/plugin marketplace add duongxthanh/claude-zalo-skills
/plugin install zalo-oa-chatbot@claude-zalo-skills

Hoặc thả skill vào trực tiếp — copy thư mục skills/creating-zalo-oa-chatbot/ vào ~/.claude/skills/.

Dùng

Trong project của bạn, chỉ cần nói với Claude:

"Cho chatbot này gửi tin handoff qua Zalo OA giúp mình."

Claude sẽ dẫn bạn qua: tạo app Zalo riêng → xác thực domain → khai Callback Url ở OA → cấp quyền lấy code → đổi lấy token → rồi copy sẵn helper zalo_oa.py vào project và gửi một tin test để xác nhận đã chạy.

Helper zalo_oa.py

File gửi tin không phụ thuộc thư viện ngoài (chỉ stdlib Python), copy thẳng vào project:

from pathlib import Path
from zalo_oa import ZaloOA

CFG = Path(__file__).resolve().parent / "config" / ".zalo-config"
oa = ZaloOA(str(CFG))
oa.send(user_id, "🔔 Có khách cần tư vấn — anh/chị vào chốt giúp nhé.")

Điểm quan trọng nhất: ZaloOA tự refresh access_token và ghi đè refresh_token đã xoay trở lại file config — nhờ đó chatbot chạy 24/7 mà không chết vì token hết hạn.

Chạy trực tiếp cũng được:

python3 zalo_oa.py config/.zalo-config exchange-code "<CODE lấy từ Console Zalo>"
python3 zalo_oa.py config/.zalo-config send - "test handoff"
python3 zalo_oa.py config/.zalo-config recent   # lấy user_id người vừa nhắn OA

Bảo mật

• App Secret + refresh_token không bao giờ vào repo. File config thật (.zalo-config) đã được .gitignore; chỉ .zalo-config.example được commit.
• Ảnh trong docs/screenshots/ đã che sẵn dữ liệu nhạy cảm (secret ẩn, SĐT/email + domain → placeholder). Xem hướng dẫn ở đó trước khi thêm ảnh mới.

Đóng góp

Rất hoan nghênh issue và PR. Mỗi skill có test stdlib chạy trong CI (python3 test_zalo_oa.py) — nếu thêm skill mới, mong bạn kèm test tương tự.

License

MIT © 2026 Duong Xuan Thanh