Connecting OpenClaw to Zalo (Vietnamese Messaging App)

Zalo is the most widely used instant messaging application in Vietnam, with over 70 million users, making it an indispensable communication channel for the Vietnamese market. OpenClaw supports Zalo Official Account (OA) integration through its plugin system, allowing you to provide AI-powered smart customer service and automated services for Vietnamese users.

Prerequisites

Before starting the configuration, you need the following:

• An OpenClaw instance deployed and running
• A Zalo Official Account (registered on the Zalo OA management platform)
• Your Zalo OA's App ID and Secret Key
• A publicly accessible webhook callback URL

Creating a Zalo Official Account

If you do not yet have a Zalo OA, you need to register and create one at oa.zalo.me. Zalo OA comes in several types; for AI bot scenarios, creating a standard OA is sufficient. Registration requires providing business information and contact details.

After creation, navigate to the "Settings" > "Developer" page in the OA management dashboard to find your App ID and Secret Key. You also need to configure the webhook URL and subscribe to relevant events on this page.

Configuring Zalo Developer Settings

In the Zalo OA developer settings, you need to complete the following:

Configure Webhook URL: Set the callback address to your OpenClaw instance's Zalo endpoint, in the format https://your-domain.com/webhooks/zalo.

Subscribe to Events: Check the "User sends message" event type so that when a user sends a message to the OA, Zalo forwards the message to your webhook address.

Obtain OA Access Token: Obtain a long-lived Access Token through the OAuth flow. Zalo Access Tokens have an expiration period and need to be periodically refreshed using a Refresh Token. OpenClaw's Zalo plugin has a built-in automatic token refresh mechanism.

Installing the Zalo Plugin

Install via the OpenClaw plugin system:

openclaw plugin install zalo

Configure using the interactive command:

openclaw channels login zalo

Enter the App ID, Secret Key, and Access Token when prompted.

Configuring openclaw.json

Manual configuration method:

{
  "channels": {
    "zalo": {
      "enabled": true,
      "appId": "your-app-id",
      "secretKey": "your-secret-key",
      "accessToken": "your-access-token",
      "refreshToken": "your-refresh-token"
    }
  }
}

With the Refresh Token configured, OpenClaw will automatically use it to obtain a new Access Token before the current one expires, ensuring uninterrupted service.

Message Type Handling

Zalo OA supports multiple message types. OpenClaw's Zalo plugin can handle the following inbound message types:

• Text messages: The most basic interaction method — users send text, AI replies with text
• Image messages: Images sent by users are converted to descriptive text or passed to a multimodal AI model for processing
• Stickers and emojis: These messages are typically ignored and do not trigger AI replies

For outbound replies, the plugin primarily uses the text message format. If the AI's reply contains image links, it can be configured to send them as image messages.

Zalo OA Messaging Rules

Zalo has some important restrictions on OA message sending:

OAs can only reply within 48 hours after a user sends a message. After 48 hours, proactively contacting a user requires using "proactive push" quota (limited monthly). OpenClaw automatically tracks each user's last message time, replying normally within the 48-hour window and logging a warning when outside it.

Additionally, Zalo requires that OA message content complies with platform policies and must not contain prohibited content.

Security Configuration

Use an allowlist to control the range of users who can interact:

{
  "channels": {
    "zalo": {
      "allowlist": ["user_id_1", "user_id_2"]
    }
  }
}

Since Zalo OA operates on a follow-based model — users must follow the OA before they can send messages — there is already a natural layer of filtering. Combined with OpenClaw's allowlist and private message pairing features, you can further tighten access control.

Considerations for the Vietnamese Market

When deploying AI services for Vietnamese users, keep the following in mind. First, the AI model needs to handle Vietnamese well, including text with diacritical marks. Second, Vietnamese users frequently communicate using stickers and emoji packs, so the Bot should handle these non-text messages gracefully. Finally, Zalo usage peaks in Vietnam are mainly during the morning and evening hours, so it is advisable to ensure service stability during these periods.

Multi-Channel Coexistence

The Zalo channel can run simultaneously with all other OpenClaw channels. If your business serves both the Vietnamese and international markets, you can use Zalo for local Vietnamese users while using WhatsApp, Telegram, and other platforms for international users. All channels share the same AI model backend and knowledge base configuration, greatly reducing operational complexity.