Skip to Content
👋 欢迎来到 HowToUseMoltbot 快速入门
频道Zalo

Zalo（Bot API）

状态：实验性。当前仅支持私聊；群组按 Zalo 文档「即将支持」。

需安装插件

Zalo 以插件形式提供，不随核心安装打包。

  • CLI 安装：moltbot plugins install @moltbot/zalo
  • 或在引导时选择 Zalo 并确认安装提示
  • 详见 插件

快速设置（入门）

  1. 安装 Zalo 插件：
    • 从源码检出：moltbot plugins install ./extensions/zalo
    • 从 npm（若已发布）：moltbot plugins install @moltbot/zalo
    • 或在引导时选择 Zalo 并确认安装提示
  2. 设置 token：
    • 环境变量：ZALO_BOT_TOKEN=...
    • 或配置：channels.zalo.botToken: "..."。
  3. 重启网关（或完成引导）。
  4. 私聊默认使用配对；首次联系时批准配对码。

最小配置：

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

说明

Zalo 是面向越南的即时通讯应用；其 Bot API 让网关可运行 1:1 对话机器人，适合客服或通知等需要确定性回传到 Zalo 的场景。

  • 由网关持有的 Zalo Bot API 频道。
  • 确定性路由：回复发回 Zalo；模型不会选择频道。
  • 私聊共享 agent 主会话。
  • 群组尚未支持（Zalo 文档标注「即将支持」）。

设置（快速路径）

1) 创建机器人 token（Zalo Bot 平台）

  1. 打开 https://bot.zaloplatforms.com  并登录。
  2. 创建新机器人并配置设置。
  3. 复制机器人 token（格式：12345689:abc-xyz）。

2) 配置 token（环境变量或配置）

示例：

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

环境变量：ZALO_BOT_TOKEN=...（仅对默认账号生效）。多账号：使用 channels.zalo.accounts，每账号单独 token 并可设 name。

  1. 重启网关。解析到 token（环境变量或配置）后 Zalo 会启动。
  2. 私聊默认配对。首次联系机器人时批准配对码。

行为说明

  • 入站消息被规范为统一频道信封，媒体以占位符表示。
  • 回复始终路由回同一 Zalo 会话。
  • 默认 long-polling；设置 channels.zalo.webhookUrl 可启用 webhook 模式。

限制

  • 出站文本按 2000 字符分块（Zalo API 限制）。
  • 媒体下载/上传受 channels.zalo.mediaMaxMb 限制（默认 5）。
  • 因 2000 字符限制使流式收益有限，默认关闭流式。

访问控制（私聊）

私聊访问

  • 默认：channels.zalo.dmPolicy = "pairing"。未知发件人收到配对码；批准前消息被忽略（配对码 1 小时后过期）。
  • 批准方式：
    • moltbot pairing list zalo
    • moltbot pairing approve zalo <CODE>
  • 配对为默认 token 交换方式。详见 配对。
  • channels.zalo.allowFrom 接受数字用户 ID（无用户名查询）。

Long-polling 与 webhook

  • 默认：long-polling（无需公网 URL）。
  • Webhook 模式：设置 channels.zalo.webhookUrl 和 channels.zalo.webhookSecret。
    • webhook 密钥需 8–256 字符。
    • Webhook URL 必须使用 HTTPS。
    • Zalo 通过 X-Bot-Api-Secret-Token 头校验事件。
    • 网关在 channels.zalo.webhookPath 处理 webhook 请求（默认使用 webhook URL 的路径）。

说明：按 Zalo API 文档，getUpdates（轮询）与 webhook 互斥。

支持的消息类型

  • 文本消息：完整支持，2000 字符分块。
  • 图片消息：下载并处理入站图片；通过 sendPhoto 发送图片。
  • 贴纸：会记录但不完全处理（无 agent 回复）。
  • 不支持类型：会记录（如受保护用户的消息）。

能力一览

功能状态
私聊✅ 支持
群组❌ 即将支持（按 Zalo 文档）
媒体（图片）✅ 支持
表态❌ 不支持
主题回复❌ 不支持
投票❌ 不支持
原生命令❌ 不支持
流式⚠️ 关闭（2000 字符限制）

投递目标（CLI/定时任务）

  • 使用会话 id 作为目标。
  • 示例：moltbot message send --channel zalo --target 123456789 --message "hi"。

故障排查

机器人无响应：

  • 检查 token 是否有效：moltbot channels status --probe
  • 确认发件人已批准（配对或 allowFrom）
  • 查看网关日志：moltbot logs --follow

Webhook 收不到事件：

  • 确认 webhook URL 使用 HTTPS
  • 确认密钥为 8–256 字符
  • 确认网关 HTTP 端点在配置路径上可访问
  • 确认未同时运行 getUpdates 轮询（二者互斥）

配置参考（Zalo）

完整配置见 配置。本频道选项：

  • channels.zalo.enabled：是否启动频道。
  • channels.zalo.botToken：Zalo Bot 平台提供的机器人 token。
  • channels.zalo.tokenFile：从文件路径读取 token。
  • channels.zalo.dmPolicy：pairing | allowlist | open | disabled（默认 pairing）。
  • channels.zalo.allowFrom：私聊白名单（用户 ID）。open 需 "*"。向导会要求数字 ID。
  • channels.zalo.mediaMaxMb：入站/出站媒体上限（MB，默认 5）。
  • channels.zalo.webhookUrl：启用 webhook 模式（需 HTTPS）。
  • channels.zalo.webhookSecret：webhook 密钥（8–256 字符）。
  • channels.zalo.webhookPath：网关 HTTP 服务上的 webhook 路径。
  • channels.zalo.proxy：API 请求的代理 URL。

多账号选项：

  • channels.zalo.accounts.<id>.botToken：每账号 token。
  • channels.zalo.accounts.<id>.tokenFile：每账号 token 文件。
  • channels.zalo.accounts.<id>.name：显示名。
  • channels.zalo.accounts.<id>.enabled：是否启用该账号。
  • channels.zalo.accounts.<id>.dmPolicy：每账号私聊策略。
  • channels.zalo.accounts.<id>.allowFrom：每账号白名单。
  • channels.zalo.accounts.<id>.webhookUrl：每账号 webhook URL。
  • channels.zalo.accounts.<id>.webhookSecret：每账号 webhook 密钥。
  • channels.zalo.accounts.<id>.webhookPath：每账号 webhook 路径。
  • channels.zalo.accounts.<id>.proxy：每账号代理 URL。
最后更新于:
WhatsAppZalo User