zalo-agent-cli

Cô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. Xây dựng trên zca-js.

Tiếng Việt | English

[!WARNING] Tool này sử dụng API Zalo không chính thức (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.

[!TIP] AI Agent Skill — Dùng với Claude Code hoặc bất kỳ agent nào hỗ trợ SKILL.md:

cp -r skill/ ~/.claude/skills/zalo-agent/   # Claude Code

15+ nhóm lệnh · listen mode + webhook · 55+ ngân hàng VN · đa tài khoản + proxy Xem skill/SKILL.md · Eval scenarios

[!NOTE] Zalo Official Account (OA) — v1.1.0 hỗ trợ Zalo OA API v3.0 chính thức:

zalo-agent oa init                                    # Setup wizard (interactive)
zalo-agent oa init --app-id <ID> --secret <KEY> --skip-webhook  # Non-interactive (AI agent)
zalo-agent oa whoami                                  # Xem thông tin OA
zalo-agent oa msg text <user-id> "Xin chào"           # Gửi tin nhắn
zalo-agent oa listen -p 3000                           # Webhook listener

OAuth login · gửi tin nhắn · quản lý follower · tag · webhook listener · VPS support Xem docs/official-account.md

[!TIP] MCP Server (AI Agent Integration) — v1.2.0 hỗ trợ Model Context Protocol cho Claude Code và các MCP client:

zalo-agent mcp start              # stdio (local Claude Code)
zalo-agent mcp start --http 3847 --auth your-secret  # HTTP (VPS)

4 tools: get_messages · send_message · list_threads · mark_read Auto-reconnect · thread filter · noise reduction · group notifications Xem MCP Guide

Cài đặt

Cách 1: Cài đặt nhanh bằng 1 câu lệnh

curl -fsSL https://raw.githubusercontent.com/therealtimex/zalo-cli/main/install.sh | bash

Cách 2: Cài đặt qua npm

npm install -g @realtimex/zalo-cli

Bắt đầu nhanh

1. Đăng nhập

zalo-agent login

Quét QR bằng Zalo app > Quét mã QR. Thông tin tự động lưu.

2. Đồng bộ dữ liệu

zalo-agent sync

Đồng bộ toàn bộ danh bạ bạn bè, nhóm và lịch sử tin nhắn gần đây vào database SQLite nội bộ để chạy mượt mà, hỗ trợ truy vấn offline và tìm kiếm nhanh.

3. Tìm bạn bè

zalo-agent friend search "Phúc"

3. Lắng nghe tin nhắn (lấy thread ID)

zalo-agent listen

Mỗi tin nhắn đến sẽ hiện threadId. Dùng --json để lấy dạng JSON.

4. Gửi tin nhắn

# Gửi cho cá nhân
zalo-agent msg send <THREAD_ID> "Xin chào!"

# Gửi vào nhóm
zalo-agent msg send <THREAD_ID> "Xin chào nhóm!" -t 1

Danh sách lệnh

Tất cả lệnh hỗ trợ --json. Tài liệu đầy đủ: Wiki

| Nhóm lệnh | Mô tả | Docs | | ------------ | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | msg | Gửi tin nhắn, hình, file, voice, video, sticker, link, thẻ chuyển khoản, QR | Tin nhắn | | friend | Danh sách, tìm, thêm, xóa, chặn, biệt danh, gợi ý | Bạn bè | | 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 | | conv | Tắt thông báo, ghim, lưu trữ, ẩn hội thoại, tự xóa | Hội thoại | | profile | Xem/cập nhật hồ sơ, ảnh đại diện, quyền riêng tư | Hồ sơ | | poll | Tạo, bỏ phiếu, đóng khảo sát | Khảo sát | | reminder | Tạo, sửa, xóa nhắc nhở | Nhắc nhở | | auto-reply | Quản lý trả lời tự động | Trả lời tự động | | quick-msg | Tin nhắn nhanh đã lưu | Tin nhắn nhanh | | label | Nhãn hội thoại | Nhãn | | catalog | zBusiness — danh mục sản phẩm | zBusiness | | listen | Lắng nghe tin nhắn real-time, webhook, lưu JSONL | Lắng nghe | | sync | Đồng bộ tin nhắn, liên hệ, nhóm vào cache SQLite | Đồng bộ | | account | Đa tài khoản & proxy | Tài khoản | | oa | Zalo Official Account API v3.0 — OAuth, tin nhắn, follower, tag, webhook | Official Account |

Xem thêm: Đa tài khoản & Proxy · Cài đặt VPS · Thẻ chuyển khoản & QR · Official Account

Tính năng

• Đăng nhập QR qua HTTP server tự động (browser + terminal)
• Đa tài khoản với proxy riêng biệt (1:1)
• 90+ lệnh phủ hết tính năng Zalo
• Zalo Official Account (OA) API v3.0 — OAuth login, gửi tin nhắn, quản lý follower, webhook listener
• Thẻ chuyển khoản (55+ ngân hàng VN) & QR VietQR
• Lắng nghe real-time với webhook & lưu JSONL local
• Output --json cho mọi lệnh — scripting & AI agents
• Credentials mã hóa tại chỗ (quyền 0600)
• Dual mode: interactive (human) + non-interactive (AI agents, CI/CD)

Ủng hộ

Nếu tool này giúp bạn tiết kiệm thời gian, hãy mua cho chúng tôi một ly cà phê!

English

CLI tool for Zalo automation — multi-account, proxy support, bank transfers, QR payments.

[!TIP] AI Agent Skill — Use with Claude Code or any SKILL.md-compatible agent:

cp -r skill/ ~/.claude/skills/zalo-agent/     # Claude Code

15+ command groups · listen mode + webhook · 55+ VN banks · multi-account + proxy See skill/SKILL.md · Eval scenarios

[!NOTE] Zalo Official Account (OA) — v1.1.0 adds official Zalo OA API v3.0:

zalo-agent oa init                                    # Setup wizard (interactive)
zalo-agent oa init --app-id <ID> --secret <KEY> --skip-webhook  # Non-interactive (AI agent)
zalo-agent oa whoami                                  # OA profile
zalo-agent oa msg text <user-id> "Hello"              # Send message
zalo-agent oa listen -p 3000                           # Webhook listener

OAuth login · messaging · follower management · tags · webhook listener · VPS support See docs/official-account.md

[!TIP] MCP Server (AI Agent Integration) — v1.2.0 adds Model Context Protocol support for Claude Code and MCP clients:

zalo-agent mcp start              # stdio (local Claude Code)
zalo-agent mcp start --http 3847 --auth your-secret  # HTTP (VPS)

4 tools: get_messages · send_message · list_threads · mark_read Auto-reconnect · thread filter · noise reduction · group notifications See MCP Guide

Installation & Quick Start

One-command installation:

curl -fsSL https://raw.githubusercontent.com/therealtimex/zalo-cli/main/install.sh | bash

Alternative global install via npm:

npm install -g @realtimex/zalo-cli

Getting started:

zalo-agent login                           # 1. Login via QR
zalo-agent sync                            # 2. Sync contacts, groups, and message history locally
zalo-agent friend search "Name"            # 3. Find a friend
zalo-agent listen                          # 4. Listen for threadId
zalo-agent msg send <THREAD_ID> "Hello!"   # 5. Send a message

Commands

Full docs: Wiki

| Group | Description | Docs | | ------------ | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | msg | Text, images, files, voice, video, stickers, links, bank cards, QR | Messages | | friend | List, find, add, remove, block, alias, recommendations | Friends | | group | Create, rename, members, settings, links, notes, invites | Groups | | conv | Mute, pin, archive, hidden, auto-delete | Conversations | | profile | Profile, avatar gallery, privacy | Profile | | poll | Create, vote, lock polls | Polls | | reminder | Create, edit, remove reminders | Reminders | | auto-reply | Auto-reply rules | Auto-Reply | | quick-msg | Saved quick messages | Quick Messages | | label | Conversation labels | Labels | | catalog | zBusiness catalogs & products | Catalog | | listen | Real-time listener, webhook, JSONL | Listener | | sync | Sync contacts, groups, and message history into SQLite | Sync | | account | Multi-account & proxy | Accounts | | oa | Zalo Official Account API v3.0 — OAuth, messaging, followers, webhook | Official Account |

Support Us

If this tool saves you time, consider buying us a coffee!

Star History

License

MIT · See DISCLAIMER.md for full terms.