Does Zalo support group chats?

Group chat support is marked as 'coming soon' in the Zalo integration. Currently, only direct messages (DMs) are supported. Check the OpenClaw documentation for updates on group chat availability.

Can I use the same Zalo bot token on multiple Gateway instances?

No. Each bot token should be used by a single Gateway instance at a time. Running the same token on multiple instances will cause message routing conflicts and missed messages.

What message types does Zalo support?

The integration supports text messages and image messages. Sticker messages are received and logged but not processed by the AI. Other media types (video, audio, files) are not currently supported in the OpenClaw Zalo integration.

How does the pairing process work on Zalo?

When dmPolicy is set to 'pairing' (the default), new users receive a random pairing code when they first message the bot. You approve them via 'openclaw pairing approve zalo ' in your terminal. Codes expire after 1 hour. Once approved, users can chat freely.

Do I need a Zalo Official Account?

No. The OpenClaw Zalo integration uses the Zalo Bot Platform, which is separate from the Official Account (OA) API. You only need a standard Zalo account and a bot created at bot.zaloplatforms.com.

Is webhook mode required?

No. Long-polling is the default mode and works without any public URL or HTTPS setup. Webhook mode is optional and recommended for production deployments where lower latency is desired.

OpenClaw GuideOpenClaw

Get Started

OpenClaw Zalo Channel

Messaging

Medium

Connect OpenClaw to Zalo using the Zalo Bot Platform. This integration lets your AI assistant send and receive messages on Vietnam's most popular messaging app. Set up a bot token, configure your DM policy, and start chatting — with support for both long-polling and webhook delivery modes.

Quick Info

DifficultyMedium

CategoryMessaging

Features Supported1 / 6

Zalo Supported Features

Text Messages

Supported

Media & Files

Not Supported

Reactions

Not Supported

Threads

Not Supported

Voice Messages

Not Supported

Group Chat

Not Supported

Zalo Prerequisites

A Zalo account with access to the Zalo Bot Platform (bot.zaloplatforms.com)
A bot token obtained from the Zalo Bot Platform dashboard
OpenClaw Gateway running and configured
For webhook mode: a publicly accessible HTTPS endpoint

Zalo Quick Setup

Create a Zalo bot and get your token

Go to bot.zaloplatforms.com, sign in with your Zalo account, and create a new bot. Copy the bot token (format: 12345689:abc-xyz) from the dashboard.

Add Zalo channel config

Add the Zalo channel configuration to ~/.openclaw/openclaw.json. Set the botToken, dmPolicy (pairing, allowlist, open, or disabled), and optionally configure webhook settings.

Start the Gateway and test

Start the Gateway with 'openclaw start'. The bot will connect via long-polling by default. Send a message to your bot on Zalo to verify the connection works.

Zalo Configuration Example

config.json

{
  "channels": {
    "zalo": {
      "enabled": true,
      "botToken": "12345689:abc-xyz",
      "dmPolicy": "pairing"
    }
  }
}

Zalo Integration Guide

Architecture Overview

OpenClaw connects to the Zalo Bot Platform API to send and receive messages. The Gateway communicates with Zalo's servers using either long-polling (default) or webhook mode. In long-polling mode, the Gateway periodically checks for new messages — no public URL or HTTPS certificate required. In webhook mode, Zalo pushes events directly to your server, which requires a publicly accessible HTTPS endpoint. Messages from Zalo users are received by the Gateway, processed by your AI, and responses are sent back through the Zalo Bot API. Each conversation is tracked per user, so multiple users can interact with the same bot independently.

Long-polling works out of the box with no network configuration. Use it for development or when you don't have a public URL.

Webhook mode offers lower latency and is recommended for production deployments with a stable HTTPS endpoint.

Creating Your Zalo Bot

To connect OpenClaw to Zalo, you need a bot token from the Zalo Bot Platform: 1. Go to bot.zaloplatforms.com and sign in with your Zalo account. 2. Click 'Create Bot' and fill in the required details (name, description, category). 3. Once created, navigate to the bot settings and copy the bot token. The bot token is the only credential needed to connect. You can provide it via the configuration file, an environment variable (ZALO_BOT_TOKEN), or read it from a file using the tokenFile option.

openclaw.json

{
  "channels": {
    "zalo": {
      "enabled": true,
      "botToken": "12345689:abc-xyz"
    }
  }
}

Store your bot token in an environment variable (ZALO_BOT_TOKEN) or a separate file (tokenFile) to avoid committing secrets to version control.

DM Policies

DM (Direct Message) policies control who can interact with your AI assistant. OpenClaw supports four policies: • pairing (default) — New users receive a pairing code when they first message the bot. You approve or deny them via 'openclaw pairing approve zalo <code>'. Codes expire after 1 hour. • allowlist — Only numeric user IDs listed in allowFrom can message the bot. Everyone else is silently ignored. • open — Anyone who messages the bot gets a response. Use with caution. • disabled — DM handling is turned off entirely.

openclaw.json

{
  "channels": {
    "zalo": {
      "dmPolicy": "allowlist",
      "allowFrom": ["123456789", "987654321"]
    }
  }
}

The 'open' policy lets anyone interact with your bot. This may consume significant AI quota if your bot is publicly discoverable on Zalo.

Webhook Configuration

By default, OpenClaw uses long-polling to receive messages. To switch to webhook mode, set the webhookUrl in your configuration. This requires a publicly accessible HTTPS endpoint. When webhook mode is enabled, long-polling is automatically disabled. Zalo sends message events directly to your webhook URL. A secret token is used for verification — Zalo includes it in the X-Bot-Api-Secret-Token HTTP header with each request. The webhookPath option lets you customize the path on your Gateway's HTTP server where Zalo events are received.

openclaw.json

{
  "channels": {
    "zalo": {
      "botToken": "12345689:abc-xyz",
      "webhookUrl": "https://your-server.com/zalo/webhook",
      "webhookSecret": "your-secret-string-8-to-256-chars",
      "webhookPath": "/zalo/webhook"
    }
  }
}

The webhookSecret must be between 8 and 256 characters long.

Webhook and long-polling are mutually exclusive — setting a webhookUrl automatically disables polling.

Message Handling

OpenClaw supports text and image messages on Zalo. Text messages are automatically chunked at 2,000 characters per message to comply with Zalo's limits. Inbound images from users are downloaded and processed. Outbound images are sent via the Zalo sendPhoto API. Sticker messages from users are logged but not processed by the bot. The mediaMaxMb setting controls the maximum file size for inbound media (default: 5 MB).

Long AI responses are automatically split into multiple messages at the 2,000-character boundary.

Streaming responses are not supported on Zalo due to the character limit constraint.

Multi-Account Setup

OpenClaw supports running multiple Zalo bot accounts simultaneously. Each account has its own bot token, DM policy, and optional webhook configuration. This is useful if you want to run separate bots for different purposes (e.g., customer support vs. internal team) under the same Gateway instance.

openclaw.json

{
  "channels": {
    "zalo": {
      "accounts": {
        "support-bot": {
          "botToken": "token-for-support-bot",
          "dmPolicy": "open"
        },
        "team-bot": {
          "botToken": "token-for-team-bot",
          "dmPolicy": "allowlist",
          "allowFrom": ["111222333"]
        }
      }
    }
  }
}

Outbound Messaging

You can send messages to specific Zalo users using the CLI. Messages are deterministically routed back to the originating Zalo chat, so responses always go to the right user. To send a manual message to a specific user, use the target flag with their numeric Zalo user ID.

terminal

openclaw message send --channel zalo --target 123456789

Proxy Configuration

If your server requires a proxy for outbound connections, you can configure one for the Zalo channel. The proxy URL is used for all API requests to Zalo's servers. This is useful in corporate environments or regions where direct access to Zalo's API endpoints may be restricted.

openclaw.json

{
  "channels": {
    "zalo": {
      "proxy": "http://proxy.example.com:8080"
    }
  }
}

Zalo Configuration Reference

Key	Type	Default	Description
enabled	boolean	false	Enable or disable the Zalo channel
botToken	string	""	Bot token from the Zalo Bot Platform (bot.zaloplatforms.com)
tokenFile	string	""	Read the bot token from a file path instead of inline configuration
dmPolicy	string	"pairing"	Controls who can DM the bot. Options: pairing, allowlist, open, disabled
allowFrom	string[]	[]	Numeric Zalo user IDs allowed to message the bot (when dmPolicy is allowlist)
mediaMaxMb	number	5	Maximum inbound media file size in megabytes
webhookUrl	string	""	HTTPS URL for webhook mode. When set, long-polling is disabled
webhookSecret	string	""	Secret string (8-256 characters) for webhook verification via X-Bot-Api-Secret-Token header
webhookPath	string	""	Custom webhook path on the Gateway HTTP server
proxy	string	""	Proxy URL for outbound API requests to Zalo
accounts.<id>.botToken	string	""	Bot token for a specific account in multi-account mode
accounts.<id>.dmPolicy	string	"pairing"	DM policy override for a specific account
accounts.<id>.webhookUrl	string	""	Webhook URL override for a specific account

enabled

Type: booleanDefault: false

Enable or disable the Zalo channel

botToken

Type: stringDefault: ""

Bot token from the Zalo Bot Platform (bot.zaloplatforms.com)

tokenFile

Type: stringDefault: ""

Read the bot token from a file path instead of inline configuration

dmPolicy

Type: stringDefault: "pairing"

Controls who can DM the bot. Options: pairing, allowlist, open, disabled

allowFrom

Type: string[]Default: []

Numeric Zalo user IDs allowed to message the bot (when dmPolicy is allowlist)

mediaMaxMb

Type: numberDefault: 5

Maximum inbound media file size in megabytes

webhookUrl

Type: stringDefault: ""

HTTPS URL for webhook mode. When set, long-polling is disabled

webhookSecret

Type: stringDefault: ""

Secret string (8-256 characters) for webhook verification via X-Bot-Api-Secret-Token header

webhookPath

Type: stringDefault: ""

Custom webhook path on the Gateway HTTP server

proxy

Type: stringDefault: ""

Proxy URL for outbound API requests to Zalo

accounts.<id>.botToken

Type: stringDefault: ""

Bot token for a specific account in multi-account mode

accounts.<id>.dmPolicy

Type: stringDefault: "pairing"

DM policy override for a specific account

accounts.<id>.webhookUrl

Type: stringDefault: ""

Webhook URL override for a specific account

Zalo Frequently Asked Questions

Zalo Troubleshooting

Bot does not receive any messages

The bot token may be invalid, expired, or the Gateway is not running. In webhook mode, the HTTPS endpoint may be unreachable.

Verify your bot token at bot.zaloplatforms.com. Check Gateway logs for connection errors. If using webhooks, confirm the endpoint is publicly accessible via HTTPS and the webhookSecret matches.

Messages are delayed or arrive in bursts

Long-polling has inherent latency compared to webhook mode. Network instability can also cause message batching.

Switch to webhook mode for lower latency. Ensure your server has a stable internet connection. Check the Gateway logs for polling interval information.

Pairing codes are not being sent to new users

The dmPolicy may not be set to 'pairing', or the bot is not properly connected to Zalo.

Verify that dmPolicy is set to 'pairing' in your configuration. Check Gateway logs to confirm the Zalo channel is online. Run 'openclaw pairing list zalo' to see pending pairing requests.

Image messages fail to send

The image file may exceed the mediaMaxMb limit, or the Zalo API may be temporarily unavailable.

Check that the image file size is under the mediaMaxMb limit (default: 5 MB). Review Gateway logs for specific API error messages. Try sending a text message first to confirm the connection is working.

Webhook verification fails

The webhookSecret in your configuration doesn't match what Zalo expects, or the endpoint is not returning the correct response.

Ensure your webhookSecret is between 8 and 256 characters. Verify the HTTPS certificate is valid (self-signed certificates are not accepted). Check that the webhookPath matches your server's routing configuration.

View Full Documentation Back to All Channels