Zalo - 越南社交平台接入 (OA)

Zalo 是越南最大的即时通讯平台，拥有超过 7000 万活跃用户。通过 Zalo Official Account（OA，官方账号）API，可以将 OpenClaw 接入 Zalo，实现面向越南用户的自动化客服和互动。

前置要求

• 一个 Zalo 个人账号
• 一个 Zalo Official Account（在 Zalo Business 中创建）
• OpenClaw Gateway（网关）已安装并运行

安装插件

openclaw plugins install @openclaw/zalo

接入步骤

第一步：创建 Zalo Official Account

1. 访问 Zalo Official Account Admin
2. 使用 Zalo 个人账号登录
3. 点击 Tạo OA（创建 OA）并填写信息
4. 完成认证（Verified OA 获得更多功能）

第二步：获取 API 凭据

1. 登录 Zalo Developers
2. 创建一个应用（Application），记录 App ID
3. 在应用设置中找到 OA 权限，关联你的 OA
4. 获取以下凭据：
   • OA ID（官方账号 ID）
   • App Secret Key
   • Access Token（需通过 OAuth 流程获取）

Token 有效期

Zalo OA Access Token 有效期较短（通常 90 天），需要定期刷新。建议配置 Refresh Token 实现自动续期。

第三步：配置 Webhook

在 Zalo Developers 的应用设置中：

1. 进入 Webhook 配置页面
2. 设置 Webhook URL：https://your-gateway/zalo/webhook
3. 勾选需要的事件类型：
   • user_send_text — 用户发送文本消息
   • user_send_image — 用户发送图片
   • follow / unfollow — 关注/取消关注

第四步：配置 OpenClaw

{
  channels: {
    zalo: {
      enabled: true,
      oaId: "YOUR_OA_ID",                      // OA ID
      appId: "YOUR_APP_ID",                     // App ID
      appSecret: "YOUR_APP_SECRET",             // App Secret Key
      accessToken: "YOUR_ACCESS_TOKEN",         // Access Token
      refreshToken: "YOUR_REFRESH_TOKEN",       // Refresh Token（推荐）
      dmPolicy: "pairing"                       // DM Policy（私信策略）
    }
  }
}

也可以通过 Environment Variable（环境变量）设置：

export ZALO_OA_ID="your-oa-id"
export ZALO_APP_ID="your-app-id"
export ZALO_APP_SECRET="your-app-secret"
export ZALO_ACCESS_TOKEN="your-access-token"
export ZALO_REFRESH_TOKEN="your-refresh-token"

第五步：重启 Gateway 并配对

openclaw gateway restart

在 Zalo 中搜索并关注你的 OA，发送消息后获取 Pairing Code（配对码）并批准：

openclaw pairing approve zalo <pairing-code>

消息类型

Zalo OA API 支持多种消息类型：

消息类型	说明
Text（文本）	纯文本消息
Image（图片）	图片消息
File（文件）	文件附件
List（列表）	列表卡片消息
Request User Info	请求用户授权信息

{
  channels: {
    zalo: {
      messageTypes: {
        enableRichMessages: true,        // 启用富消息格式
        fallbackToText: true              // 不支持时降级为文本
      }
    }
  }
}

Token 自动刷新

{
  channels: {
    zalo: {
      tokenRefresh: {
        enabled: true,                    // 启用自动刷新
        refreshBefore: 86400              // 过期前 24 小时刷新（秒）
      }
    }
  }
}

OA 类型与限制

OA 类型	消息限制	API 功能
未认证	有限	基础 API
已认证（Verified）	较多	完整 API
企业认证	最多	完整 API + 高级功能

认证建议

建议完成 OA 认证以获得完整的 API 功能和更高的消息配额。

DM Policy（私信策略）

策略	说明
pairing	用户需先获取 Pairing Code（配对码）验证
allowlist	仅允许指定 Zalo User ID 私聊
open	所有关注者均可私聊

常见问题

Webhook 不触发

1. 确认 Webhook URL 可从公网访问（HTTPS）
2. 确认已勾选需要的事件类型
3. 在 Zalo Developers 中测试 Webhook 连通性

Access Token 过期

1. 确认 Refresh Token 配置正确
2. 检查 tokenRefresh.enabled 是否为 true
3. 手动刷新：访问 Zalo Developers 重新获取 Token

消息发送被限制

1. 确认 OA 认证状态
2. 检查是否超出 API 调用频率限制
3. Zalo 对未认证 OA 有严格的消息限额

🇨🇳 中国用户须知

Zalo 主要在越南使用，适合面向越南市场的跨境业务。

网络访问：Zalo API 服务器在中国大陆可访问，但可能有延迟。建议将 Gateway 部署在东南亚区域的云服务器上（如新加坡、越南）。

适用场景：面向越南用户的跨境电商客服、越南本地化业务支持、东南亚区域市场运营。

语言支持：Zalo 界面和 API 文档主要为越南语，建议团队中有越南语能力的成员负责 OA 配置和内容审核。

注册提示：Zalo 注册需要越南手机号（+84），中国手机号无法直接注册。创建 OA 也需要越南本地的认证信息。