Zalo

​

Bundled plugin

• Install: openclaw plugins install @openclaw/zalo
• Pinned version: openclaw plugins install @openclaw/zalo@2026.6.11
• From a local checkout: openclaw plugins install ./path/to/local/zalo-plugin
• Details: Plugins

​

Quick setup

1. Create a bot token at https://bot.zaloplatforms.com (sign in, create a bot, configure settings). The token is numeric_id:secret; for Marketplace bots the usable runtime token may appear in the bot’s welcome message.
2. Set the token, either as env ZALO_BOT_TOKEN=... (default account only) or in config.
3. Restart the gateway.
4. Approve the pairing code on first DM contact (default DM policy is pairing).

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

​

What it is

​

How it works

• Inbound messages are normalized into the shared channel envelope with media placeholders.
• Replies always route back to the same Zalo chat; quote-reply is not used (replyToMode is fixed off).
• Long-polling (getUpdates) by default; webhook mode available via channels.zalo.webhookUrl.
• Groups require an @mention to trigger the bot; this is not configurable per channel.

​

Limits

​

Access control

​

Direct messages

• channels.zalo.dmPolicy: pairing (default) | allowlist | open | disabled.
• Pairing: unknown senders get a pairing code; messages are ignored until approved. Codes expire after 1 hour.
  • openclaw pairing list zalo
  • openclaw pairing approve zalo <CODE>
  • Details: Pairing
• channels.zalo.allowFrom accepts numeric Zalo user IDs (no username lookup). open requires "*".

​

Groups

• channels.zalo.groupPolicy: open | allowlist | disabled.
• channels.zalo.groupAllowFrom restricts which sender IDs can trigger the bot in groups; falls back to allowFrom when unset.
• Default resolution: when channels.zalo is configured, an unset groupPolicy resolves to open. When channels.zalo is missing entirely, runtime fails closed to allowlist.
• Reported real-world caveat: on some Marketplace-bot setups the bot could not be added to a group at all. If you hit that, verify with your bot’s Zalo Bot Platform settings; it is a platform-side constraint, not an OpenClaw policy.

​

Long-polling vs webhook

• Default: long-polling (no public URL required).
• Webhook mode: set channels.zalo.webhookUrl and channels.zalo.webhookSecret.
  • Webhook URL must use HTTPS.
  • Webhook secret must be 8-256 characters.
  • Zalo sends events with an X-Bot-Api-Secret-Token header, checked with a constant-time comparison.
  • Gateway HTTP handles webhook requests at channels.zalo.webhookPath (defaults to the webhook URL’s path).
  • Requests must use Content-Type: application/json (or a +json media type).
  • getUpdates polling and webhook are mutually exclusive per Zalo API docs.

​

Supported message types

• Text: full support, chunked to 2000 characters.
• Media: inbound/outbound, capped by mediaMaxMb.
• Reactions, threads, polls, native commands: not supported by the plugin.
• Streaming: the plugin declares block-streaming capability, but Zalo has no dedicated outbound queue/merge-text tuning knobs (unlike some other regional channels); verify current behavior in your environment if this matters for your use case.

​

Capabilities

​

Delivery targets (CLI/cron)

openclaw message send --channel zalo --target 123456789 --message "hi"

​

Troubleshooting

• Check the token: openclaw channels status --probe
• Verify the sender is approved (pairing or allowFrom)
• Check gateway logs: openclaw logs --follow

• Confirm the webhook URL uses HTTPS
• Confirm the secret is 8-256 characters
• Confirm the gateway HTTP endpoint is reachable on the configured path
• Confirm getUpdates polling is not also running (they are mutually exclusive)
• A burst of requests can return HTTP 429 (120 requests / 60s per path+IP); back off and retry

​

Configuration reference

​

Related

• Channels Overview - all supported channels
• Pairing - DM authentication and pairing flow
• Groups - group chat behavior and mention gating
• Channel Routing - session routing for messages
• Security - access model and hardening