{"_rev":"4-8eae107817d07a6e937962d0c9b97caa","time":{"created":"2026-07-05T06:47:09.643Z","modified":"2026-07-05T06:47:10.337Z","1.0.6":"2026-07-05T05:16:25.673Z","1.0.7":"2026-07-05T06:47:09.962Z"},"_id":"@ardennguyen/zalo-agent-cli","name":"@ardennguyen/zalo-agent-cli","dist-tags":{"latest":"1.0.7"},"versions":{"1.0.7":{"name":"@ardennguyen/zalo-agent-cli","version":"1.0.7","description":"CLI tool for Zalo automation — multi-account, proxy, bank transfers, QR payments, Official Account API v3.0","type":"module","bin":{"zalo-agent":"src/index.js"},"main":"./src/index.js","scripts":{"test":"node --test src/*.test.js src/**/*.test.js","lint":"eslint src/","lint:fix":"eslint src/ --fix","format":"prettier --write src/","format:check":"prettier --check src/","release":"npm version patch -m 'release: v%s' && git push origin main --tags","prepublishOnly":"npm run lint && npm test"},"keywords":["zalo","cli","automation","messaging","vietnam","proxy","vietqr","zca-js","official-account","zalo-oa","webhook"],"repository":{"type":"git","url":"git+https://github.com/ardennguyen/zalo-agent-cli.git"},"author":{"name":"ardennguyen"},"license":"MIT","publishConfig":{"access":"public"},"engines":{"node":">=22"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","chalk":"^5.6.2","commander":"^15.0.0","express":"^5.2.1","https-proxy-agent":"^9.1.0","node-fetch":"^3.3.2","undici":"^8.5.0","zca-js":"^2.1.2","zod":"^4.4.3"},"devDependencies":{"eslint":"^10.0.3","prettier":"^3.8.1"},"_id":"@ardennguyen/zalo-agent-cli@1.0.7","gitHead":"7d1de0c84e7855e8458a21320fd18c6baf629efb","bugs":{"url":"https://github.com/ardennguyen/zalo-agent-cli/issues"},"homepage":"https://github.com/ardennguyen/zalo-agent-cli#readme","_nodeVersion":"22.23.1","_npmVersion":"10.9.8","dist":{"integrity":"sha512-/ajG6RmkNa7xQNFEDdcjZ6mvzdnveClnHGtsl2Zli5tYeB5qusNjbTc6xM/Nq5SzJtaXHywG67KwHAt0P2LF/w==","shasum":"2a7cc7eb1c9a375a13fffa78d5d4019fc6f05a54","tarball":"https://registry.npmjs.org/@ardennguyen/zalo-agent-cli/-/zalo-agent-cli-1.0.7.tgz","fileCount":52,"unpackedSize":373745,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@ardennguyen%2fzalo-agent-cli@1.0.7","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCj36KZUrALJp3VMdYnxnL7hf827a3gquTocsmt3ODUJgIhALLrJgaI5OVSF2o8WcImDzw2x2XUZBIdQvSrGVa/3A4K"}]},"_npmUser":{"name":"ardennguyen","email":"arden.h.nguyen@gmail.com"},"directories":{},"maintainers":[{"name":"ardennguyen","email":"arden.h.nguyen@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/zalo-agent-cli_1.0.7_1783234029836_0.9857365855180868"},"_hasShrinkwrap":false}},"maintainers":[{"name":"ardennguyen","email":"arden.h.nguyen@gmail.com"}],"description":"CLI tool for Zalo automation — multi-account, proxy, bank transfers, QR payments, Official Account API v3.0","homepage":"https://github.com/ardennguyen/zalo-agent-cli#readme","keywords":["zalo","cli","automation","messaging","vietnam","proxy","vietqr","zca-js","official-account","zalo-oa","webhook"],"repository":{"type":"git","url":"git+https://github.com/ardennguyen/zalo-agent-cli.git"},"author":{"name":"ardennguyen"},"bugs":{"url":"https://github.com/ardennguyen/zalo-agent-cli/issues"},"license":"MIT","readme":"<p align=\"center\">\n  <img src=\"assets/mascot.png\" width=\"120\" alt=\"zalo-agent-cli mascot\" />\n</p>\n\n# zalo-agent-cli\n\nCông cụ CLI tự động hóa Zalo — đa tài khoản, proxy, chuyển khoản ngân hàng, thanh toán QR.\nXây dựng trên [zca-js](https://github.com/RFS-ADRENO/zca-js).\n\n**[Tiếng Việt](#bắt-đầu-nhanh)** | **[English](#english)**\n\n> [!WARNING]\n> Tool này sử dụng API Zalo **không chính thức** ([zca-js](https://github.com/RFS-ADRENO/zca-js)). Zalo không hỗ trợ và **tài khoản của bạn có thể bị khóa hoặc ban**. Tự chịu trách nhiệm. Không liên kết với Zalo hay VNG. Xem [DISCLAIMER.md](DISCLAIMER.md).\n\n> [!TIP]\n> **AI Agent Skill** — Dùng với OpenClaw, Claude Code, hoặc bất kỳ agent nào hỗ trợ SKILL.md:\n> ```bash\n> clawhub install zalo-agent          # OpenClaw (từ ClawHub registry)\n> cp -r skill/ ~/.claude/skills/zalo-agent/   # Claude Code\n> ```\n> 15+ nhóm lệnh · listen mode + webhook · 55+ ngân hàng VN · đa tài khoản + proxy\n> Xem [skill/SKILL.md](skill/SKILL.md) · [Eval scenarios](skill/evals/)\n\n> [!NOTE]\n> **Zalo Official Account (OA)** — Zalo OA API v3.0 chính thức:\n> ```bash\n> zalo-agent oa init                                    # Setup wizard (interactive)\n> zalo-agent oa init --app-id <ID> --secret <KEY> --skip-webhook  # Non-interactive (AI agent)\n> zalo-agent oa whoami                                  # Xem thông tin OA\n> zalo-agent oa msg text <user-id> \"Xin chào\"           # Gửi tin nhắn\n> zalo-agent oa listen -p 3000                           # Webhook listener\n> ```\n> OAuth login · gửi tin nhắn · quản lý follower · tag · webhook listener · VPS support\n> Xem [docs/official-account.md](docs/official-account.md)\n\n> [!TIP]\n> **MCP Server (AI Agent Integration)** — Model Context Protocol cho Claude Code và các MCP client:\n> ```bash\n> zalo-agent mcp start              # stdio (local Claude Code)\n> zalo-agent mcp start --http 3847 --auth your-secret  # HTTP (VPS)\n> ```\n> 4 tools: get_messages · send_message · list_threads · mark_read\n> Auto-reconnect · thread filter · noise reduction · group notifications\n> Xem [MCP Guide](skill/references/mcp-guide.md)\n\n---\n\n## Cài đặt\n\n```bash\nnpm install -g @ardennguyen/zalo-agent-cli\n```\n\n## Bắt đầu nhanh\n\n### 1. Đăng nhập\n\n```bash\nzalo-agent login\n```\n\nQuét QR bằng **Zalo app > Quét mã QR**. Thông tin tự động lưu.\n\n### 2. Tìm bạn bè\n\n```bash\nzalo-agent friend search \"Phúc\"\n```\n\n### 3. Lắng nghe tin nhắn (lấy thread ID)\n\n```bash\nzalo-agent listen\n```\n\nMỗi tin nhắn đến sẽ hiện `threadId`. Dùng `--json` để lấy dạng JSON.\n\n### 4. Gửi tin nhắn\n\n```bash\n# Gửi cho cá nhân\nzalo-agent msg send <THREAD_ID> \"Xin chào!\"\n\n# Gửi vào nhóm\nzalo-agent msg send <THREAD_ID> \"Xin chào nhóm!\" -t 1\n```\n\n---\n\n## Danh sách lệnh\n\nTất cả lệnh hỗ trợ `--json`. Tài liệu đầy đủ: **[Wiki](https://github.com/ardennguyen/zalo-agent-cli/wiki)**\n\n| Nhóm lệnh | Mô tả | Docs |\n|------------|--------|------|\n| `msg` | Gửi tin nhắn, hình, file, voice, video, sticker, link, thẻ chuyển khoản, QR | [Tin nhắn](https://github.com/ardennguyen/zalo-agent-cli/wiki/Tin-Nh%E1%BA%AFn) |\n| `friend` | Danh sách, tìm, thêm, xóa, chặn, biệt danh, gợi ý | [Bạn bè](https://github.com/ardennguyen/zalo-agent-cli/wiki/B%E1%BA%A1n-B%C3%A8) |\n| `group` | Tạo, đổi tên, thành viên, cài đặt, link, ghi chú, lời mời | [Nhóm & Cộng đồng](https://github.com/ardennguyen/zalo-agent-cli/wiki/Nh%C3%B3m) |\n| `conv` | Tắt thông báo, ghim, lưu trữ, ẩn hội thoại, tự xóa | [Hội thoại](https://github.com/ardennguyen/zalo-agent-cli/wiki/H%E1%BB%99i-Tho%E1%BA%A1i) |\n| `profile` | Xem/cập nhật hồ sơ, ảnh đại diện, quyền riêng tư | [Hồ sơ](https://github.com/ardennguyen/zalo-agent-cli/wiki/H%E1%BB%93-S%C6%A1) |\n| `poll` | Tạo, bỏ phiếu, đóng khảo sát | [Khảo sát](https://github.com/ardennguyen/zalo-agent-cli/wiki/Kh%E1%BA%A3o-S%C3%A1t) |\n| `reminder` | Tạo, sửa, xóa nhắc nhở | [Nhắc nhở](https://github.com/ardennguyen/zalo-agent-cli/wiki/Nh%E1%BA%AFc-Nh%E1%BB%9F) |\n| `auto-reply` | Quản lý trả lời tự động | [Trả lời tự động](https://github.com/ardennguyen/zalo-agent-cli/wiki/Tr%E1%BA%A3-L%E1%BB%9Di-T%E1%BB%B1-%C4%90%E1%BB%99ng) |\n| `quick-msg` | Tin nhắn nhanh đã lưu | [Tin nhắn nhanh](https://github.com/ardennguyen/zalo-agent-cli/wiki/Tin-Nh%E1%BA%AFn-Nhanh) |\n| `label` | Nhãn hội thoại | [Nhãn](https://github.com/ardennguyen/zalo-agent-cli/wiki/Nh%C3%A3n) |\n| `catalog` | zBusiness — danh mục sản phẩm | [zBusiness](https://github.com/ardennguyen/zalo-agent-cli/wiki/zBusiness) |\n| `listen` | Lắng nghe tin nhắn real-time, webhook, lưu JSONL | [Lắng nghe](https://github.com/ardennguyen/zalo-agent-cli/wiki/L%E1%BA%AFng-Nghe) |\n| `account` | Đa tài khoản & proxy | [Tài khoản](https://github.com/ardennguyen/zalo-agent-cli/wiki/T%C3%A0i-Kho%E1%BA%A3n) |\n| **`oa`** | **Zalo Official Account API v3.0 — OAuth, tin nhắn, follower, tag, webhook** | **[Official Account](https://github.com/ardennguyen/zalo-agent-cli/wiki/Official-Account)** |\n\nXem thêm: [Đa tài khoản & Proxy](https://github.com/ardennguyen/zalo-agent-cli/wiki/%C4%90a-T%C3%A0i-Kho%E1%BA%A3n-&-Proxy) · [Cài đặt VPS](https://github.com/ardennguyen/zalo-agent-cli/wiki/C%C3%A0i-%C4%90%E1%BA%B7t-VPS) · [Thẻ chuyển khoản & QR](https://github.com/ardennguyen/zalo-agent-cli/wiki/Th%E1%BA%BB-Chuy%E1%BB%83n-Kho%E1%BA%A3n-&-QR) · [Official Account](https://github.com/ardennguyen/zalo-agent-cli/wiki/Official-Account)\n\n---\n\n## Tính năng\n\n- Đăng nhập QR qua HTTP server tự động (browser + terminal)\n- Đa tài khoản với proxy riêng biệt (1:1)\n- 90+ lệnh phủ hết tính năng Zalo\n- **Zalo Official Account (OA) API v3.0** — OAuth login, gửi tin nhắn, quản lý follower, webhook listener\n- Thẻ chuyển khoản (55+ ngân hàng VN) & QR VietQR\n- Lắng nghe real-time với webhook & lưu JSONL local\n- Output `--json` cho mọi lệnh — scripting & AI agents\n- Credentials mã hóa tại chỗ (quyền 0600)\n- **Dual mode**: interactive (human) + non-interactive (AI agents, CI/CD)\n\n---\n\n\n\n---\n\n## English\n\nCLI tool for Zalo automation — multi-account, proxy support, bank transfers, QR payments.\n\n> [!TIP]\n> **AI Agent Skill** — Use with OpenClaw, Claude Code, or any SKILL.md-compatible agent:\n> ```bash\n> clawhub install zalo-agent                    # OpenClaw (from ClawHub registry)\n> cp -r skill/ ~/.claude/skills/zalo-agent/     # Claude Code\n> ```\n> 15+ command groups · listen mode + webhook · 55+ VN banks · multi-account + proxy\n> See [skill/SKILL.md](skill/SKILL.md) · [Eval scenarios](skill/evals/)\n\n> [!NOTE]\n> **Zalo Official Account (OA)** — Official Zalo OA API v3.0:\n> ```bash\n> zalo-agent oa init                                    # Setup wizard (interactive)\n> zalo-agent oa init --app-id <ID> --secret <KEY> --skip-webhook  # Non-interactive (AI agent)\n> zalo-agent oa whoami                                  # OA profile\n> zalo-agent oa msg text <user-id> \"Hello\"              # Send message\n> zalo-agent oa listen -p 3000                           # Webhook listener\n> ```\n> OAuth login · messaging · follower management · tags · webhook listener · VPS support\n> See [docs/official-account.md](docs/official-account.md)\n\n> [!TIP]\n> **MCP Server (AI Agent Integration)** — Model Context Protocol support for Claude Code and MCP clients:\n> ```bash\n> zalo-agent mcp start              # stdio (local Claude Code)\n> zalo-agent mcp start --http 3847 --auth your-secret  # HTTP (VPS)\n> ```\n> 4 tools: get_messages · send_message · list_threads · mark_read\n> Auto-reconnect · thread filter · noise reduction · group notifications\n> See [MCP Guide](skill/references/mcp-guide.md)\n\n### Quick Start\n\n```bash\nnpm install -g @ardennguyen/zalo-agent-cli\nzalo-agent login                           # 1. Login via QR\nzalo-agent friend search \"Name\"            # 2. Find a friend\nzalo-agent listen                          # 3. Listen for threadId\nzalo-agent msg send <THREAD_ID> \"Hello!\"   # 4. Send a message\n```\n\n### Commands\n\nFull docs: **[Wiki](https://github.com/ardennguyen/zalo-agent-cli/wiki)**\n\n| Group | Description | Docs |\n|-------|-------------|------|\n| `msg` | Text, images, files, voice, video, stickers, links, bank cards, QR | [Messages](https://github.com/ardennguyen/zalo-agent-cli/wiki/Messages) |\n| `friend` | List, find, add, remove, block, alias, recommendations | [Friends](https://github.com/ardennguyen/zalo-agent-cli/wiki/Friends) |\n| `group` | Create, rename, members, settings, links, notes, invites | [Groups](https://github.com/ardennguyen/zalo-agent-cli/wiki/Groups) |\n| `conv` | Mute, pin, archive, hidden, auto-delete | [Conversations](https://github.com/ardennguyen/zalo-agent-cli/wiki/Conversations) |\n| `profile` | Profile, avatar gallery, privacy | [Profile](https://github.com/ardennguyen/zalo-agent-cli/wiki/Profile) |\n| `poll` | Create, vote, lock polls | [Polls](https://github.com/ardennguyen/zalo-agent-cli/wiki/Polls) |\n| `reminder` | Create, edit, remove reminders | [Reminders](https://github.com/ardennguyen/zalo-agent-cli/wiki/Reminders) |\n| `auto-reply` | Auto-reply rules | [Auto-Reply](https://github.com/ardennguyen/zalo-agent-cli/wiki/Auto-Reply) |\n| `quick-msg` | Saved quick messages | [Quick Messages](https://github.com/ardennguyen/zalo-agent-cli/wiki/Quick-Messages) |\n| `label` | Conversation labels | [Labels](https://github.com/ardennguyen/zalo-agent-cli/wiki/Labels) |\n| `catalog` | zBusiness catalogs & products | [Catalog](https://github.com/ardennguyen/zalo-agent-cli/wiki/Catalog) |\n| `listen` | Real-time listener, webhook, JSONL | [Listener](https://github.com/ardennguyen/zalo-agent-cli/wiki/Listener) |\n| `account` | Multi-account & proxy | [Accounts](https://github.com/ardennguyen/zalo-agent-cli/wiki/Accounts) |\n| **`oa`** | **Zalo Official Account API v3.0 — OAuth, messaging, followers, webhook** | **[Official Account](https://github.com/ardennguyen/zalo-agent-cli/wiki/Official-Account)** |\n\n\n\n---\n\n## License\n\n[MIT](LICENSE) · See [DISCLAIMER.md](DISCLAIMER.md) for full terms.\n","readmeFilename":"README.md"}