Channels
Opclaw Zalo
By Fully-featured OpenClaw Zalo channel plugin powered by zca-js, with messaging, groups, access control, and agent tool integration.
Install
npm install
#Configuration Example
{
"channels": {
"opclaw-zalo": {
"accounts": {
"default": {
"enabled": true
}
}
}
}
}README
# opclaw-zalo
[](https://github.com/monasprox/opclaw-zalo/actions/workflows/ci.yml)
[](LICENSE)
[](https://github.com/nicholasxuu/openclaw)
[](https://nodejs.org/)
**OpenClaw channel plugin** that connects your Zalo personal account as a fully-featured messaging channel — powered by [zca-js](https://github.com/nicholasxuu/zca-js).
> **🤖 For AI Agents:** See [**docs/agent-install.md**](docs/agent-install.md) — complete installation guide + detailed usage reference for all 147 actions with parameters, examples, and message flow.
---
🚀 Join the Zalo Community. Get the plugin, updates, and real-world automation use cases. https://zalo.me/g/gigr4cnahvidpewxk74z
## Why
Zalo is Vietnam's dominant messaging platform (~75M users) but has no official bot API for personal accounts. This plugin bridges that gap by connecting a Zalo personal account to OpenClaw's agent framework — enabling AI-powered conversations, tool execution, and automation directly through Zalo chat.
## Features
### Core
- **147 Zalo API actions** exposed as agent tools — messaging, friends, groups, polls, reminders, profile, catalogs, notes, settings, and more
- **QR code login** — authenticate via terminal or control panel, credentials auto-persist
- **DM & Group support** — per-account policies: `open`, `pairing`, `allowlist`, `disabled`
- **Mention gating** — in groups, bot only responds when @mentioned (configurable per group)
- **Image processing** — downloads and analyzes images sent with @mention; buffers images from non-mention messages so they're available as context when the bot is mentioned later
### Message Features
- **Rich text** — send styled messages with bold, italic, underline, strikethrough, colors (markdown auto-converted)
- **Urgency** — mark messages as important (`urgency: 1`) or urgent (`urgency: 2`)
- **Reply/quote context** — when a user replies to a message, the AI receives the quoted message content and sender
- **File sending** — send any file type (PDF, docs, etc.) via local path or URL
- **Reaction acknowledgment** — react to incoming messages (configurable: heart, like, haha, etc.)
- **Quote reply** — reply to specific messages with context threading
- **Read receipts** — mark messages as read
- **Sticker support** — search and send native Zalo stickers via agent tool calls
- **Auto-unsend** — recall sent messages
- **Typing indicator** — show typing status while processing
### Access Control
- **Per-user allow/deny lists** — global and per-group
- **Pairing mode** — code-based DM authorization for unknown users
- **Group policies** — open, allowlist, or disabled per group
- **Command authorization** — restrict control commands to allowed users
---
## Quick Start
### Prerequisites
- [OpenClaw](https://github.com/nicholasxuu/openclaw) ≥ 2026.2.0
- Node.js ≥ 22
- A Zalo personal account
### Install
```bash
# Clone the plugin
git clone https://github.com/monasprox/opclaw-zalo.git /path/to/opclaw-zalo
# Install dependencies
cd /path/to/opclaw-zalo && npm install
# Register with OpenClaw
openclaw plugins install --link /path/to/opclaw-zalo
# Restart gateway
openclaw gateway restart
```
### Login
```bash
# Show QR code in terminal — scan with Zalo app
openclaw channels login --channel opclaw-zalo
```
After scanning, credentials are saved. Subsequent gateway restarts auto-login.
### Verify
```bash
openclaw status
```
You should see `opclaw-zalo` listed under channels with status `ON`.
---
## Configuration
All configuration lives in `~/.openclaw/openclaw.json` under `channels.opclaw-zalo`.
### Minimal Config
```jsonc
{
"channels": {
"opclaw-zalo": {
"accounts": {
"default": {
"enabled": true
}
}
}
}
}
```
### Full Config Example
```jsonc
{
"channels": {
"opclaw-zalo": {
"accounts": {
"default": {
"enabled": true,
// DM access policy
"dmPolicy": "open", // open | pairing | allowlist | disabled
"allowFrom": ["*"], // Zalo user IDs or "*" for all
"denyFrom": [], // Block specific users
// Group access policy
"groupPolicy": "open", // open | allowlist | disabled
// Per-group overrides (key = group ID, name, or "*" for default)
"groups": {
"*": {
"requireMention": true // Default: only respond when @mentioned
},
"123456789": {
"allow": true,
"requireMention": false, // Always respond in this group
"allowUsers": [], // Empty = all users allowed
"denyUsers": []
}
},
// Display
"markdown": {
"tables": "bullets" // off | bullets | code | block
},
"messagePrefix": "",
"responsePrefix": ""
}
}
}
}
}
```
### Configuration Reference
#### Account Settings
| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `enabled` | `boolean` | `true` | Enable/disable this account |
| `dmPolicy` | `string` | `"open"` | DM access: `open` / `pairing` / `allowlist` / `disabled` |
| `allowFrom` | `string[]` | `["*"]` | Users allowed to DM (IDs or `*`) |
| `denyFrom` | `string[]` | `[]` | Users blocked from all interaction |
| `groupPolicy` | `string` | `"open"` | Group access: `open` / `allowlist` / `disabled` |
| `messagePrefix` | `string` | `""` | Text prepended to every outbound message |
| `responsePrefix` | `string` | `""` | Text prepended to agent responses |
#### Per-Group Settings (`groups.<id>`)
| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `allow` | `boolean` | — | Explicitly allow/deny this group |
| `requireMention` | `boolean` | `false` | Only respond when @mentioned |
| `allowUsers` | `string[]` | `[]` | Only these users trigger the bot |
| `denyUsers` | `string[]` | `[]` | Block specific users in this group |
| `tools` | `object` | — | Per-group tool execution policy |
#### DM Policies
| Policy | Behavior |
|--------|----------|
| `open` | Accept all DMs |
| `pairing` | Require code exchange for unknown users |
| `allowlist` | Only `allowFrom` users can DM |
| `disabled` | Block all DMs |
---
## Agent Tools
The plugin exposes **147 actions** as a single `opclaw-zalo` agent tool. The agent selects the action by name. Names and group names are auto-resolved to Zalo numeric IDs.
### Messaging (16 actions)
| Action | Description |
|--------|-------------|
| `send` | Send text message (supports `urgency` and `messageTtl`) |
| `send-styled` | Send message with rich text (bold, italic, underline, strike, colors) |
| `send-link` | Send a URL with preview |
| `send-image` | Send image by URL |
| `send-file` | Send any file (PDF, doc, etc.) by local path or URL |
| `send-video` | Send video by URL |
| `send-voice` | Send voice message by URL |
| `send-sticker` | Send sticker by ID or keyword search |
| `send-card` | Send contact card |
| `send-bank-card` | Send bank card info |
| `send-typing` | Send typing indicator |
| `send-to-stranger` | Send message to non-friend |
| `forward-message` | Forward message to multiple threads (supports TTL) |
| `delete-message` | Delete a message |
| `undo-message` | Recall a sent message |
| `add-reaction` | React to a message (heart, like, haha, wow, cry, angry) |
### Friends (16 actions)
| Action | Description |
|--------|-------------|
| `friends` | List all friends (with search/filter) |
| `find-user` | Find user by phone number (returns full profile) |
| `find-user-by-username` | Find user by Zalo username |
| `send-friend-request` | Send friend request (supports name resolution) |
| `get-friend-requests` | List pending friend requests |
| `accept-friend-request` | Accept a friend request |
| `reject-friend-request` | Reject a friend request |
| `get-sent-requests` | List sent friend requests |
| `undo-friend-request` | Cancel a sent friend request |
| `unfriend` | Remove a friend |
| `check-friend-status` | Check friend/request status |
| `set-friend-nickname` | Set nickname for a friend |
| `remove-friend-nickname` | Remove friend nickname |
| `get-online-friends` | List online friends |
| `get-close-friends` | List close friends |
| `get-friend-recommendations` | Get friend recommendations |
### Groups (22 actions)
| Action | Description |
|--------|-------------|
| `groups` | List all groups (with search) |
| `get-group-info` | Get group details |
| `create-group` | Create a new group |
| `add-to-group` | Add members to a group |
| `remove-from-group` | Remove member from group |
| `leave-group` | Leave a group |
| `rename-group` | Rename a group |
| `add-group-admin` / `remove-group-admin` | Manage group admins |
| `change-group-owner` | Transfer group ownership |
| `disperse-group` | Dissolve a group |
| `update-group-settings` | Update group settings (name lock, msg history, join approval, etc.) |
| `enable-group-link` / `disable-group-link` / `get-group-link` | Manage group invite links |
| `get-pending-members` / `review-pending-members` | Manage join requests |
| `block-group-member` / `unblock-group-member` / `get-group-blocked` | Group member blocking |
| `get-group-members-info` | Get detailed member info |
| `join-group-link` / `invite-to-groups` / `get-group-invites` / `join-group-invite` / `delete-group-invite` | Group invitations |
| `change-group-avatar` | Change group avatar |
| `upgrade-group-to-community` | Upgrade group to community |
| `get-group-chat-history` | Get group message history |
### Polls (6 actions)
| Action | Description |
|--------|-----
... (truncated)
channels
Comments
Sign in to leave a comment