Setting Up the Zalo Channel

I have spent many hours trying to bridge different messaging platforms into a single workflow. It is often a headache to figure out regional APIs when you just want your agent to talk to users where they already are. If you are building for users in Vietnam, Zalo is the platform you need to support.

The Zalo Bot API is currently experimental in OpenClaw and focuses on direct messages. I recommend using this for support or notifications because it uses deterministic routing, meaning replies always go back to the original Zalo chat.

What You’ll Need

• A Zalo Bot Platform account
• The OpenClaw CLI installed
• A bot token (format: 12345689:abc-xyz)
• An HTTPS URL (required only if you choose webhook mode)

Quick Start

The Zalo channel is a plugin, so it is not part of the core install. You can get it running in about five minutes by following these steps.

1. Install the Plugin

You can install the plugin via the CLI or select it during the onboarding process. Use this command:

openclaw plugins install @openclaw/zalo

2. Get Your Token

Head over to https://bot.zaloplatforms.com, sign in, and create a new bot. Copy the bot token provided in your settings.

3. Configure the Gateway

You can set your token as an environment variable (ZALO_BOT_TOKEN) or add it to your configuration file. Here is a minimal config example:

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

4. Restart and Approve

Restart your gateway. By default, Zalo uses a “pairing” policy for security. When you first message the bot, it will send you a pairing code. You need to approve it using the CLI:

• List pending codes: openclaw pairing list zalo
• Approve a code: openclaw pairing approve zalo <CODE>

Troubleshooting

If things aren’t working as expected, check these common issues found in the documentation.

Bot doesn’t respond

• Run openclaw channels status --probe to see if your token is actually valid.
• Verify that the sender is approved via the pairing process or the allowFrom list.
• Check your logs with openclaw logs --follow.

Webhook not receiving events

• Ensure your webhookUrl uses HTTPS and your webhookSecret is between 8 and 256 characters.
• Confirm that the gateway HTTP endpoint is reachable.
• Make sure you aren’t trying to use long-polling and webhooks at the same time; they are mutually exclusive.

If you run into a specific configuration hurdle, you can get help from the AI Setup Assistant.

What’s Next

• Plugin Management
• Pairing Details
• Configuration Reference
• CLI Message Commands