Zalo

​

Bundled plugin

• Install: openclaw plugins install @openclaw/zalo
• Pinned version: openclaw plugins install @openclaw/zalo@<version> (pin only for reproducible installs)
• 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. Check openclaw channels status --probe; start the Gateway if it is offline. Config changes follow hot reload. If you changed the service environment, restart the Gateway to load it.
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).
  • OpenClaw returns HTTP 200 only after it durably stores the raw event. Storage failures return HTTP 500. The durable 200 carries x-openclaw-delivery-accepted: durable. Reverse proxies can require that header to distinguish OpenClaw acceptance from a generic 200. Authentication, validation, and storage-error responses omit it.
  • 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.
• Photo captions: truncated to fit the 2000-character limit, including polling replies.
• Reactions, threads, polls, native commands: not supported by the plugin.
• Streaming: the plugin declares block-streaming capability. 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