Zalo (Bot API)

Zalo Bot API integration for DMs and groups with image support, long-polling or webhook mode, popular in Vietnam.

Zalo is Vietnam's most popular messaging platform with approximately 75 million users, and OpenClaw's Zalo Bot API integration brings AI agent capabilities to this massive user base. The plugin connects through Zalo's official Bot Platform, supporting both long-polling (no public URL required) and webhook modes for receiving messages, making it accessible to developers regardless of their hosting setup. The integration handles DMs and group chats with image send/receive support. Messages are automatically chunked at 2000 characters to comply with Zalo's API limits. Access control follows standard OpenClaw patterns: pairing (approval required), allowlist, open, or disabled for both DMs and groups. Multi-account support lets you connect multiple Zalo bots from a single OpenClaw instance. Long-polling mode is the standout feature for ease of deployment — unlike webhook mode, it doesn't require a publicly accessible URL or SSL certificate setup. This makes it ideal for developers running OpenClaw locally or behind NAT. Webhook mode is available for production deployments that need lower latency and more reliable message delivery. As an experimental integration, the Zalo Bot API plugin covers the essentials (text, images, DMs, groups) but lacks advanced features like reactions, polls, threads, or file attachments beyond images. For businesses and developers targeting the Vietnamese market, this integration provides a direct path to deploying AI assistants on the platform where their users already communicate daily.

Tags: messaging, vietnam, asia

Category: Messaging

Use Cases

  • AI customer service bot for Vietnamese businesses on Zalo
  • Personal AI assistant for Vietnamese users on their preferred platform
  • E-commerce product recommendation bot on Zalo
  • Vietnamese language AI tutor accessible via Zalo
  • Business automation bot for small Vietnamese enterprises
  • Multi-platform AI deployment including Zalo for Vietnamese market coverage

Tips

  • Start with long-polling mode for development — no public URL needed
  • Switch to webhook mode for production to get lower latency and more reliable delivery
  • Use dmPolicy: 'pairing' initially to control who can interact with your bot
  • Set up multi-account if you need separate bot personas for different use cases
  • Monitor the Zalo Bot Platform dashboard for API usage and error rates
  • Test image send/receive early — it's the only media type supported
  • Use groupPolicy: 'allowlist' to control which Zalo groups the bot participates in

Known Issues & Gotchas

  • Zalo Bot Platform registration typically requires a Vietnamese phone number
  • Long-polling mode is easier to set up but has slightly higher latency than webhook mode
  • Messages are chunked at 2000 characters — long AI responses will be split
  • Image support is for send/receive only — other file types are not supported
  • Bot API documentation is primarily in Vietnamese — use translation tools
  • Webhook mode requires HTTPS — self-signed certificates may not work
  • Multi-account env vars follow standard OpenClaw patterns — additional accounts must use config
  • Experimental status means the API surface may change between OpenClaw versions

Alternatives

  • Zalo Personal (zalouser)
  • Telegram
  • WhatsApp
  • WeChat

Community Feedback

Zalo is Vietnam's most popular messaging app (~75M users). Their Bot API provides a Telegram-like interface with polling/webhook modes. Having OpenClaw support for Zalo opens up the Vietnamese market.

— GitHub Discussions

The long-polling mode for Zalo is great — no need for a public URL. I run OpenClaw on my laptop and it just works. Perfect for testing before going to production.

— Reddit r/selfhosted

Zalo: Vietnam-focused messaging platform with Bot API. The integration supports both polling and webhook modes, making it accessible regardless of your hosting setup.

— Hivelocity Blog

Frequently Asked Questions

Is the Zalo plugin bundled with OpenClaw?

No. Zalo is a separate plugin: openclaw plugins install @openclaw/zalo. It's not included in the core OpenClaw package.

Do I need a public URL for the Zalo bot?

Not if you use long-polling mode (mode: 'polling'). This connects outbound to Zalo's servers and doesn't require a public URL or SSL. Webhook mode requires a publicly accessible HTTPS endpoint.

Can I register a Zalo bot without a Vietnamese phone number?

The Zalo Bot Platform typically requires a Vietnamese phone number for registration. Some developers use virtual Vietnamese numbers or work with local partners to set up their bot accounts.

What's the difference between the Zalo and Zalo Personal plugins?

The Zalo plugin uses the official Bot API — stable and supported by Zalo. The Zalo Personal plugin (zalouser) uses unofficial APIs via zca-js to automate a personal account — more features but may break if Zalo changes their protocol.

Does Zalo support sending files?

Only images are supported for send/receive. Other file types (documents, audio, video) are not supported through the Bot API integration. Use Telegram or WhatsApp if you need full file exchange.

Is the Zalo integration stable for production use?

It's marked as experimental, meaning the API surface may change between OpenClaw versions. The underlying Zalo Bot API is stable, but the OpenClaw integration is still maturing. Test thoroughly before deploying to production.

Configuration Examples

Long-polling setup (easiest)

channels:
  zalo:
    enabled: true
    botToken: "your-zalo-bot-token"
    mode: "polling"
    dmPolicy: pairing

Webhook mode for production

channels:
  zalo:
    enabled: true
    botToken: "your-zalo-bot-token"
    mode: "webhook"
    webhookUrl: "https://gateway.example.com/webhook/zalo"
    dmPolicy: allowlist
    allowFrom:
      - "user-id-1"
      - "user-id-2"

Multi-account with groups

channels:
  zalo:
    enabled: true
    accounts:
      main:
        botToken: "token-main"
        mode: "polling"
        dmPolicy: pairing
      support:
        botToken: "token-support"
        mode: "webhook"
        webhookUrl: "https://gateway.example.com/webhook/zalo-support"
        groupPolicy: open

Installation

openclaw plugins install @openclaw/zalo