Hermes Zalo Plugin 🤖💬

Kết nối Hermes Agent với Zalo — Vietnam's leading messaging platform. Connect Hermes Agent to Zalo Bot Platform via official Bot API.

📦 Overview

A platform plugin for Hermes Agent that adds Zalo messaging support. Built as a drop-in plugin — zero modifications to Hermes core required.

✨ Features

Feature	Status
📨 Send/receive text messages (2000-char chunks)	✅
🖼️ Send photos from URL	✅
⌨️ Typing indicator (`sendChatAction`)	✅
🔄 Long-polling (`getUpdates`)	✅
🌐 Webhook mode (via aiohttp)	✅
🔐 DM captcha + core pairing approval	✅
📋 Allowlist / Open access policies	✅
📬 Cron delivery (`deliver=zalo`)	✅
⚙️ Interactive setup wizard (`hermes gateway setup`)	✅
📦 Zero extra dependencies (uses httpx, already a Hermes dep)	✅
👥 Group management (create, kick, admin, poll, pin, invite)	✅ v2
📝 Slash commands (/menu, /warn, /kick, /promote, /poll, /pin...)	✅ v2
🛡️ Zero-token anti-spam + warn system	✅ v2
📜 Chat history sync (JSONL, search)	✅ v2
👥 CRM contacts (import/export CSV, search by phone)	✅ v2
📊 Group info, member list, announcements	✅ v2

🗺️ Roadmap

🚀 Quick Start

1. Install the plugin

# Clone to user plugins directory
git clone https://github.com/moken627-hub/hermes-plugin-zalo.git \
    ~/.hermes/plugins/zalo

2. Create a Zalo Bot

Go to https://bot.zaloplatforms.com
Sign in with your Zalo account
Create a new bot and copy the Bot Token (format: numeric_id:secret)

3. Configure

# Option A: Environment variable (recommended)
export ZALO_BOT_TOKEN="your_bot_token_here"

# Option B: Interactive setup
hermes gateway setup zalo

# Option C: config.yaml
Add to `~/.hermes/config.yaml`:

```yaml
gateway:
  platforms:
    zalo:
      enabled: true
      extra:
        bot_token: "your_bot_token_here"
        dm_policy: "pairing"   # "pairing" | "open" | "allowlist"


### 4. Enable & restart

```bash
hermes plugins enable zalo-platform
hermes gateway restart

5. Verify

hermes gateway status
# You should see Zalo listed with your bot name

🔧 Configuration

Environment Variables

Variable	Required	Description
`ZALO_BOT_TOKEN`	✅	Bot token from bot.zaloplatforms.com
`ZALO_ALLOWED_USERS`	❌	Comma-separated user IDs (require `allowlist` policy)
`ZALO_ALLOW_ALL_USERS`	❌	`true` to allow all users (anyone can use your bot)
`ZALO_HOME_CHANNEL`	❌	Default Zalo chat ID for cron delivery

Adapter slash commands (/follow, /silent, /kick, …) run only for users in ZALO_ALLOWED_USERS (or when ZALO_ALLOW_ALL_USERS=true). Messages to the agent are additionally authorized by the Hermes gateway: with no allowlist, unknown users must be approved via hermes pairing approve zalo <code>.

Access Policies

Policy	Description
`pairing` (default)	New users receive a 6-digit captcha code to prove they can read the chat (expires in 1 hour). Real approval is Hermes core pairing: `hermes pairing approve zalo <code>`.
`open`	Any user can message the bot
`allowlist`	Only users in `allowed_users` can message

Webhook Mode (Production)

For production, use webhook instead of long-polling:

gateway:
  platforms:
    zalo:
      enabled: true
      extra:
        bot_token: <your-bot-token>
        webhook_url: "https://your-domain.com/webhook/zalo"
        webhook_secret: <random-16-256-char-secret>
        webhook_port: 8443      # optional, default 8443
        webhook_host: 127.0.0.1 # optional, default 127.0.0.1 (loopback)

The listener speaks plain HTTP and binds to 127.0.0.1 by default; run it behind a TLS reverse proxy that forwards POST /webhook/zalo. Set webhook_host: 0.0.0.0 only if you need it reachable on all interfaces.

Then configure your webhook URL in the Zalo Bot Platform dashboard.

📁 Project Structure

hermes-plugin-zalo/
├── zalo/
│   ├── __init__.py          # Plugin entry point (exports register)
│   ├── adapter.py           # Full Zalo adapter + moderation + group mgmt
│   ├── plugin.yaml          # Plugin metadata & config schema
│   ├── group_manager.py     # Group management (create/kick/admin/poll/pin)
│   ├── moderation.py        # Anti-spam, warn system, CRM, history sync
│   └── ...
├── examples/
│   └── config.yaml          # Example configuration
├── .github/
│   └── ISSUE_TEMPLATE/
│       ├── bug_report.md
│       └── feature_request.md
├── CONTRIBUTING.md          # Contribution guidelines
├── SECURITY.md              # Security policy
├── LICENSE                  # MIT License
└── README.md                # This file

🧩 API Reference

The plugin implements the Zalo Bot Platform REST API:

Endpoint	Method	Purpose
`getMe`	POST	Verify bot token
`getUpdates`	POST	Long-poll for new messages
`sendMessage`	POST	Send text (max 2000 chars)
`sendPhoto`	POST	Send image from URL
`sendChatAction`	POST	Show typing indicator
`setWebhook`	POST	Configure webhook URL
`deleteWebhook`	POST	Remove webhook config

Full API docs: bot.zapps.me/docs

🧪 Development

# Install in editable mode for development
ln -s $(pwd)/zalo ~/.hermes/plugins/zalo

# Run syntax check
python -m py_compile zalo/adapter.py

# Test import
cd /path/to/hermes-agent
python -c "from gateway.platforms.base import BasePlatformAdapter; print('OK')"

📝 Changelog

v2.0.0 (2026-08-02)

🎉 Major release — Enterprise-grade Zalo moderation and group management
👥 Group management: create, kick, promote/demote admin, invite, poll, pin
🔇 Mute/Unmute group via Bot API
🔕 Silent mode (only reply when @tagged or called by name)
🎉 Welcome message for new members
📋 Group tracking/follow (chat history + memory per group)
🏷️ Name triggers (auto-reply when bot is mentioned by name)
⚙️ Per-group toggle settings (muted, silent, welcome, follow)
📊 Group settings dashboard (/settings command)
📝 Slash commands: /menu, /rules, /warn, /kick, /promote, /poll, /pin, /noi-quy, /info, /mute, /unmute, /silent, /welcome, /follow, /name-trigger, /settings
🛡️ Zero-token anti-spam: rate limiting + suspicious link detection
⚠️ Warn system: 3-strike moderation with expiry
📜 Chat history sync: JSONL-based, searchable, flush-to-disk
👥 CRM contacts: add/search/list, CSV import/export, per-group labels
📊 Group info, member list, announcements, group link management

v1.0.0 (2026-05-10)

Initial release
Text messaging (send/receive)
Photo sending
Typing indicator
Long-polling & webhook modes
DM captcha challenge + Hermes core pairing approval
Allowlist/Open access policies
Cron delivery support
Interactive setup wizard

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md first.

🐛 Found a bug? Open an issue
💡 Have an idea? Submit a feature request
🔀 Want to contribute? Send a PR!

📄 License

🙏 Acknowledgements

Hermes Agent — The open-source AI agent that grows with you
Zalo Bot Platform — Zalo's official bot API
Nous Research — Creator of Hermes Agent

zalo-platform

What it adds

Environment variables it needs 1

README