The Free, Transparent & Autonomous Zalo AI Agent Engine for Developers, Hermes, Claude Code, and Multi-Agent Frameworks.
Install once · run with 1 command or browser QR · AI Agents connect via Model Context Protocol (MCP) to manage Zalo autonomously, safely, and transparently.
| Core Advantage | ABS Zalo Agent Engine | Conventional Bots & Scrapers |
|---|---|---|
| Pricing & Freedom | 100% Free & Open-Source (MIT) | Paid licenses / Black-box scripts |
| Architecture | Dual-Adapter: Personal QR + Official OA (Webhook) | Single unofficial scraping adapter |
| Safety & Privacy | Fail-Closed PolicyGuard + Secret Redaction | No guardrails (high ban/checkpoint risk) |
| AI Integration | Native Model Context Protocol (MCP Stdio Server) | Raw HTTP webhooks / Manual glue code |
| Code Quality | 138/138 Automated Unit & Integration Tests | Little to no test coverage |
| Multi-Agent Ready | Hermes Agent, Claude Code, OpenAI Codex, Cursor | Single-system or standalone CLI only |
abs-zalo-bot là hạ tầng Zalo AI Agent mã nguồn mở miễn phí, an toàn và minh bạch nhất cho các nhà phát triển và doanh nghiệp:
- Zalo Cá nhân (Personal Engine): Quản trị nhóm chuyên sâu (Kick thành viên, chuyển nhượng Trưởng nhóm, bổ nhiệm Phó nhóm), tạo & khoá bình chọn (Polls), thả reaction emoji, thu hồi tin nhắn (Recall/Undo), và tự động ghi nhận ngữ cảnh (Corpus Listener).
- Zalo Official Account (OA Doanh nghiệp): Webhook 2 chiều chuẩn bảo mật HMAC, tự động tiếp nhận khách hàng, hỗ trợ phân loại Lead Generation & CSKH 24/7.
- Bảo mật & Minh bạch (Fail-Closed Policy Guard): Tự động che giấu OTP/thông tin nhạy cảm, chống spam, bảo vệ an toàn tài khoản Zalo.
- Chuẩn Quốc Tế MCP (Model Context Protocol): Kết nối trực tiếp và cấp quyền cho AI Agents (Hermes, Claude Code, Codex, Cursor...) làm việc tự chủ mà không cần viết thêm API wrapper.
Attach npx abs-zalo-bot or node mcp/server.js to your Agent configuration:
| Category | Tool Name | Description |
|---|---|---|
| Telemetry & Health | abs_zalo_status |
Check bridge status, safety flags, and message corpus count |
abs_zalo_list_groups |
List allowlisted source & destination groups | |
abs_zalo_recent_messages |
Read captured message streams with full metadata | |
abs_zalo_corpus_summary |
Get aggregated inventory of users, groups, and logs | |
| Group Administration | abs_zalo_rename_group |
Rename group name (Admin/Leader required) |
abs_zalo_change_group_avatar |
Change group avatar image from URL or file | |
abs_zalo_create_group_note |
Create and pin announcement/note at the top | |
abs_zalo_get_pending_members |
List members waiting for approval to join | |
abs_zalo_review_pending_member |
Approve or reject pending member requests | |
abs_zalo_block_group_member |
Block a member permanently from the group | |
abs_zalo_unblock_group_member |
Unblock a previously blocked member | |
abs_zalo_get_group_link |
Get public group invite link (URL) | |
abs_zalo_set_group_link |
Enable or disable public group join link | |
abs_zalo_update_group_settings |
Configure group permissions (lock chat, pin, etc.) | |
abs_zalo_kick_member |
Remove a member from a group (Admin/Owner required) | |
abs_zalo_transfer_owner |
Transfer group ownership (Owner required) | |
abs_zalo_add_deputy |
Promote a member to Group Deputy / Admin | |
abs_zalo_remove_deputy |
Demote a Group Deputy back to regular member | |
abs_zalo_invite_member |
Invite / add a user into a group | |
| Interaction & Polls | abs_zalo_create_poll |
Create interactive polls with custom options |
abs_zalo_lock_poll |
Lock / close an active voting poll | |
abs_zalo_react_message |
Send emoji reactions to messages (/:heart, /:like, etc.) |
|
abs_zalo_undo_message |
Recall / undo a previously sent message | |
| Personal lifecycle | abs_zalo_personal_action |
Explicitly confirmed rich message/reply/mention/file, sticker, voice/video, forward, typing, group lifecycle/settings and friend lifecycle actions |
| Agent readiness | abs_zalo_readiness |
Read-only checklist for connection, destination, Hermes brain, profile and safe live mode |
| Capability packs | abs_zalo_capability_packs |
Shows the active reader / operator / admin MCP guard level |
| Discovery & Intel | abs_zalo_get_user_info |
Fetch public user profile by userId |
abs_zalo_get_group_info |
Fetch group settings and metadata | |
abs_zalo_find_user |
Lookup user profile by phone number | |
abs_zalo_list_friends |
List all friends of the account | |
abs_zalo_list_all_groups |
Fetch all joined groups from Zalo server |
- Node.js 22.5.0+ (LTS recommended) on any OS: Windows, macOS, Linux.
- Zero C++ compilation tools required — utilizes pure JavaScript with Node.js built-in
node:sqlite.
- Clone repository:
git clone https://github.com/teddiesloco/abs-zalo-bot.git cd abs-zalo-bot - Setup (1-Click):
- Double-click
setup.bat(or in PowerShell run.\setup.ps1). - It will automatically verify Node.js, install packages, and initialize local configuration.
- Double-click
- Start Bot:
- Double-click
start.bat(or runnpm start). - It will launch the bot and automatically open
http://localhost:3871/connectin your browser.
- Double-click
- Login: Scan the QR code on the browser screen with your Zalo app on your phone.
💡 Run 24/7 in Background on Windows (without keeping CMD open):
npm install -g pm2 pm2 start src/cli.js --name abs-zalo-bot pm2 startup pm2 save
- Clone & Setup:
git clone https://github.com/teddiesloco/abs-zalo-bot.git cd abs-zalo-bot ./install.sh - Start the Bot:
npm start
- Login:
Open
http://127.0.0.1:3871/connectin Safari/Chrome to scan the QR code.
- Start with Docker Compose:
docker compose up -d
- Login:
Open
http://localhost:3871/connectin your browser to scan the QR code. - Check Logs:
docker compose logs -f
For headless servers and 24/7 background operation:
./setup.sh
sudo cp abs-zalo-bot.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now abs-zalo-bot(On headless VPS, view QR via SSH tunnel: ssh -N -L 13871:127.0.0.1:3871 user@your-vps then open http://127.0.0.1:13871/connect).
Add one or more [[agent_profiles]] blocks to private config.toml to give each account or destination an owner-authored identity, mission, voice, operating rules, knowledge anchors and intended tool pack. These fields are inserted only into the Hermes system instruction; inbound Zalo messages cannot rewrite them.
Start MCP with ABS_ZALO_TOOL_PACK=reader (default). Move deliberately to operator for reactions/polls/recall, or admin for group and personal lifecycle actions. This is an extra MCP guard; explicit confirmation and bridge policy still apply.
Set HERMES_ZALO_MEDIA_INGEST=true only on the private bridge host to stage inbound Zalo attachments for an authenticated Hermes platform plugin. The bridge returns opaque attachment references and serves the staged local file through its authenticated /v1/hermes/media/:eventId/:attachmentId endpoint; it never passes provider CDN URLs or Zalo session data to Hermes. Images, documents, audio/voice and video are bounded to 25 MB for images/files and 100 MB for audio/video.
hermes-plugin/platforms/zalo is an installable Hermes gateway adapter. It polls the authenticated local bridge and converts only normalized, approved Zalo events into Hermes MessageEvents; it never handles QR, cookies, sessions or arbitrary zca-js calls.
Before it receives a single event, set all of HERMES_ZALO_GATEWAY_ENABLED=true, a non-empty HERMES_ZALO_ALLOWED_THREADS, and a non-empty HERMES_ZALO_ALLOWED_USERS. Sender references are privacy-safe hashes returned by the bridge—not a display name. Groups default to HERMES_ZALO_GROUP_MODE=mention. The plugin can connect with HERMES_ZALO_ALLOW_AUTOREPLY=false, but reply/typing remain rejected until that separate opt-in is set to true.
For profile-aware quality, select gateway_skill = "your-owner-authored-hermes-skill" in each [[agent_profiles]] record. Hermes then auto-loads that skill for that source/profile, while the bridge still owns policy, confirmation, audit and outbound bounds. Detailed installation: hermes-plugin/README.md.
abs-zalo-bot automatically compiles Markdown syntax and brand color tags into native Zalo TextStyle formatting:
# Heading 1: Large Header (f_18) + Bold (b) + Ruby Red (c_db342e).## Heading 2: Header Bold (b) + Emerald Green (c_15a85f).### Heading 3: Header Bold (b) + Amber Orange (c_f27806).**bold**: Zalo Bold (b).*italic*: Zalo Italic (i).__underline__: Zalo Underline (u).~~strikethrough~~: Zalo StrikeThrough (s).- Color tags:
[RED]...[/RED](Ruby Red),[GREEN]...[/GREEN](Emerald Green),[ORANGE]...[/ORANGE](Amber Orange),[YELLOW]...[/YELLOW](Royal Gold) — supports Vietnamese equivalents[ĐỎ],[XANH],[CAM],[VÀNG]. - Safe Styled Chunker (
formatAndChunkZaloMarkdown): Splits long output without dropping characters or breaking UTF-16 surrogate pairs. Every bubble is capped at 2,000 UTF-16 code units, 40 styles, and 3,000 encoded bytes; styles are clipped and rebased per bubble.
Turn raw command-line AI into a warm, reliable, enterprise-grade Zalo AI Assistant in 60 seconds across 5 structured knowledge layers:
| Layer | File | Purpose |
|---|---|---|
| 1. Soul | template_soul.md |
Core service philosophy, patience, empathy & outcome-driven mindset |
| 2. Persona | template_persona.md |
Natural Vietnamese mobile chat tone, anti-AI-slop & F-shape reading layout |
| 3. Identity | template_identity.md |
Role definition, RBAC boundaries, autonomous actions vs owner approval |
| 4. Memory | template_memory.md |
Durable facts storage for recurring customers without context bloat |
| 5. Context | template_context.md |
Business catalog, pricing packages, sales policies & intake workflows |
To scaffold a complete 5-layer profile for your Hermes Agent, simply run:
bash templates/zalo-agent-scaffolding/setup.sh my-zalo-assistant
hermes --profile my-zalo-assistantRead full documentation at docs/5-layer-agent-framework.md.
Ready-to-use "Digital Brain" template for Hermes Agent:
SOUL.md: Conversational, warm, Vietnamese executive assistant voice (zero corporate slop, short mobile-optimized sentences, authentic tone).AGENT.md: Deterministic AI architecture, safety rules, fail-closed boundaries, mention-only in groups.skills/zalo-customer-care: 1-on-1 customer service, empathetic problem diagnosis, and natural lead qualification.skills/zalo-community-admin: 24/7 group moderation (new member welcome, FAQ answering, rule pinning, spam defense).
To enable, run 1 command:
cp -R hermes-plugin/starter-kit/skills/* ~/.hermes/skills/
cat hermes-plugin/starter-kit/SOUL.md >> ~/.hermes/SOUL.mdHermes Native Platform Release — 1-click Hermes integration, dual-tier role-based security, live dashboard telemetry, and modular zero-bloat MCP extensibility.
| Feature | Detail |
|---|---|
| 1-Click Hermes Installer | Run npm run install:hermes to automatically detect Hermes layout, atomically merge config.yaml, and enable platforms/zalo. |
| Diagnostic Doctor | Run npm run doctor to execute an 11-point health check verifying plugins, tokens, and bridge connectivity. |
| Dual-Tier Toolsets | Owner Mode (zalo_owner): Owner UID unlocks full Hermes terminal, file I/O, browser, and skills.Public Mode ( zalo_public): Safe conversational tools only, blocking terminal and file tampering from strangers. |
| Live Dashboard Telemetry | Full bi-directional event stream rendered in real-time on Hermes Agent Dashboard / Web UI. |
| Dual LLM Model Setup | Direct API Keys (BYOK): Anthropic, OpenAI, Gemini AI Studio, DeepSeek. OAuth Subscription Proxies: Connect flat-rate accounts via 9Router, Cockpit Proxy, Omnirouter, or LiteLLM ( provider: custom, base_url: http://127.0.0.1:8181/v1) for zero-token billing and unlimited reasoning! |
| Lean Modular Architecture | Zero bloated dependencies in core. Connect any local or cloud tool (ZeroTTS, yt-dlp, deep research) on-demand via standard MCP. |
Rich-message reliability release — complete long replies, quoted context, and broader media normalization.
| Feature | Detail |
|---|---|
| Lossless Styled Chunking | Long Markdown replies are rendered once, split on readable boundaries, then sent sequentially. Each bubble stays within 2,000 UTF-16 code units, 40 styles, and 3,000 encoded bytes. Styles are clipped and rebased instead of discarded. |
| Safe Delivery Semantics | A quote appears only on the first bubble; an attachment only on the last. Plain-text retry occurs only after a numeric provider rejection. Ambiguous network failures are not retried, preventing likely duplicate sends. |
| Quoted Context | Quoted text and media become normalized Hermes context. Provider URLs remain staging inputs and are excluded from model-facing raw metadata. |
| Media Normalization | Additional Zalo media URL fields are classified and staged through the existing jail and SSRF protections. |
If you already installed abs-zalo-bot, upgrade to v0.9.2 after backing up your runtime data:
- If installed via NPM:
npm install -g abs-zalo-bot@latest
- If cloned via Git:
git pull origin main npm install
- If running via Docker:
docker compose pull && docker compose up -d
The upgrade does not intentionally modify
data/sessions/,data/bridge.sqlite3, or.env. Back them up before upgrading; reconnection behavior still depends on the active Zalo session.
If ABS Zalo Bot helps your operations or business, please consider starring the repository:
# Star via GitHub CLI
gh repo star teddiesloco/abs-zalo-botOr click Star directly at: https://github.com/teddiesloco/abs-zalo-bot ⭐
- Side-effect control: Every outbound message and administrative action is audited through
PolicyGuard. - Credential isolation: Session cookies and tokens are kept in private local storage; never exposed over prompts or logs.
- Fail-closed default: Inbound events are listener-only until explicitly allowlisted.
- Explicit side effects: Personal lifecycle actions require
confirm: trueat the local bridge; file attachments are accepted only beneathABS_ZALO_MEDIA_ROOT.
Built with ❤️ by ABS (Agent Business System) for the Global & Vietnamese AI Agent Community.