All plugins

zalo-platform

Zalo Bot Platform gateway adapter for Hermes Agent — relays messages between Zalo DMs/groups and the agent over the official Bot API (bot-api.zaloplatforms.com), long-polling or webhook mode. Adds slash commands and moderation. Zero extra dependencies (uses httpx, already a Hermes dependency). Production-tested on multiple Vietnamese deployments. Disclosure — connects to the third-party Zalo Bot API (bot-api.zaloplatforms.com) with your bot token; long-polling by default, or opt-in webhook mode with a listener on 127.0.0.1 by default that checks the X-Bot-Api-Secret-Token header; the setup wizard writes ZALO_* values to ~/.hermes/.env; group chat history is stored locally under <HERMES_HOME>/zalo-history.

moken627-hub11Platformv2.1.3Updated 1 month ago

About

Zalo Bot Platform gateway adapter for Hermes Agent — relays messages between Zalo DMs/groups and the agent over the official Bot API (bot-api.zaloplatforms.com), long-polling or webhook mode. Adds slash commands and moderation. Zero extra dependencies (uses httpx, already a Hermes dependency). Production-tested on multiple Vietnamese deployments. Disclosure — connects to the third-party Zalo Bot API (bot-api.zaloplatforms.com) with your bot token; long-polling by default, or opt-in webhook mode with a listener on 127.0.0.1 by default that checks the X-Bot-Api-Secret-Token header; the setup wizard writes ZALO_* values to ~/.hermes/.env; group chat history is stored locally under <HERMES_HOME>/zalo-history.

Hermes Zalo Plugin 🤖💬

License: MIT
Hermes Agent
Python
PRs Welcome
Zalo Bot Platform

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

FeatureStatus
📨 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

  • Sticker sending/receiving
  • Image/file upload (multipart)
  • Voice message support
  • Rich text formatting (bold/italic/color)
  • Zalo labels sync

🚀 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

  1. Go to https://bot.zaloplatforms.com
  2. Sign in with your Zalo account
  3. 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

VariableRequiredDescription
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

PolicyDescription
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>.
openAny user can message the bot
allowlistOnly 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:

EndpointMethodPurpose
getMePOSTVerify bot token
getUpdatesPOSTLong-poll for new messages
sendMessagePOSTSend text (max 2000 chars)
sendPhotoPOSTSend image from URL
sendChatActionPOSTShow typing indicator
setWebhookPOSTConfigure webhook URL
deleteWebhookPOSTRemove 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.


📄 License

MIT © 2026 Moken


🙏 Acknowledgements

README from the reviewed commit 5a98936; it updates when the author re-pins.

More by moken627-hub

2 plugins by moken627-hub in the catalog.

Developer Mode

Explore built-in Hermes toolsets and actions.

HermesAgent

Developer?

Create a Hermes extension for Desktop or agent workflows.

Developer Section