将 Zalo OA 接入 ChatHub 收件箱

本文解决什么问题#

ChatHub 的 Zalo OA 渠道会接收客户发给 Zalo 官方账号（Official Account）的消息，客服可以直接在统一收件箱中回复，并支持客户发送的图片、文件和位置。它走 Zalo 官方 Open API，与个人 Zalo 渠道（扫码登录）完全不同：OA 是企业账号，稳定且符合 Zalo 的条款。

配置分为两侧。在 Zalo for Developers 一侧，你要准备一个应用，让 OA 给该应用授权，然后取出三个值：App ID、Secret Key 和刷新令牌。在 ChatHub 一侧，把这三个值粘贴进去，把 ChatHub 提供的 Webhook URL 复制到 Zalo，再点击“连接”。整个过程约十五分钟。

要通过 webhook 接收消息，ChatHub 系统必须拥有可从公网访问的 HTTPS 域名。Zalo 只向 HTTPS 地址推送事件，因此位于 NAT 之后或仅有内网地址的服务器，在拥有公网域名之前收不到消息。

1. 开始之前的准备#

1. 1

   一个已审核通过的 Zalo 官方账号，且你是该 OA 的管理员（才能给应用授权）。

2. 2

   一个用于登录 developers.zalo.me（Zalo for Developers）的 Zalo 账号。

3. 3

   拥有公网 HTTPS 域名的 ChatHub 系统（例如 https://chat.company.com）。若还没有，请在 webhook 步骤之前先配置域名。

4. 4

   ChatHub 的管理员权限，以便打开“渠道”页面并添加账号。

2. 准备应用并给 OA 授权（在 Zalo for Developers）#

这一步完全在 Zalo for Developers 上完成。目标是拥有一个应用，并让你的官方账号授予该应用管理权限——这是下一步获取刷新令牌的前提。

1. 1

   打开 developers.zalo.me 并用你的 Zalo 账号登录。

2. 2

   创建一个新应用，并给它取一个便于识别的名称。

3. 3

   在应用中添加 Official Account 产品并关联你的 OA：选择 OA 并授予应用管理该 OA 的权限。该授权必须由 OA 管理员确认。

4. 4

   验证应用的域名：按 Zalo 的验证步骤，在应用的域名区域登记你的 ChatHub 系统域名（即公网 HTTPS 域名）。缺少这一步，Zalo 可能拒绝向你的地址推送 webhook。

3. 获取 App ID、Secret Key 和刷新令牌#

ChatHub 需要恰好三个值。App ID 和 Secret Key 属于应用；刷新令牌代表 OA 刚刚授予应用的权限。

1. 1

   App ID 和 Secret Key：在 Zalo for Developers 打开应用信息页。App ID 显示在基本信息中；Secret Key 在应用的密钥区域。两者都复制下来。

2. 2

   刷新令牌：OA 给应用授权后，Zalo 会颁发一个授权码；通过 Zalo 的 OAuth v4 流程把它换成 access token + refresh token（或使用 Zalo 提供的获取 OA 令牌的辅助工具）。ChatHub 需要的是刷新令牌。

3. 3

   保存这三个值以便在第 5 步粘贴到 ChatHub。不要通过聊天或邮件发送它们。

4. 在 ChatHub 中添加 Zalo OA 渠道#

1. 1

   在 ChatHub 中进入“管理 → 渠道”，点击右上角的“添加账号”。

2. 2

   在对话框的渠道类型一栏中，选择 Zalo OA（Official Account）。

3. 3

   填写便于识别的渠道名称，例如“门店 Zalo OA”——该名称只在 ChatHub 内部用于区分同类渠道。

4. 4

   把 App ID 粘贴到 App ID 输入框，Secret Key 粘贴到 Secret Key 输入框，刷新令牌粘贴到 Refresh token 输入框。Access token 输入框为可选——留空则 ChatHub 在连接时用刷新令牌自动获取访问令牌。

1. 1

   滚动到表单底部的“Zalo 应用的 Webhook URL”区块。点击“复制”获取 webhook 地址——形如 https://<你的域名>/api/channels/webhooks/zalo-oa，本系统的所有 OA 渠道共用该地址。

2. 2

   在 Zalo for Developers 中，打开应用的 Official Account → Webhook，把复制的地址粘贴到 Webhook URL 并保存。确保应用域名已验证（第 2 步）。

3. 3

   回到 ChatHub，点击“创建账号”。渠道配置对话框打开，此时状态为“已断开”。

5. 连接并验证#

1. 1

   在刚打开的渠道对话框中点击“连接”。ChatHub 会调用 Zalo 验证密钥并读取 OA 身份。

2. 2

   几秒后状态从“已断开”变为“运行中”，渠道名称和头像会被替换成 OA 自身的名称与图片。

3. 3

   用手机给 OA 发一条测试消息。打开 ChatHub 的“消息”页面：新会话会出现，并带有 Zalo 标识。从 ChatHub 回复，确认消息送达 Zalo 上正确的客户。

出现问题时，ChatHub 会把原因直接写在渠道上，而不是丢出 Zalo 的原始错误码：

1. 1

   Zalo 拒绝刷新访问令牌——刷新令牌已过期或已在别处使用（例如有人在 Zalo for Developers 重新获取了令牌）。重新给应用授权以获得新的刷新令牌，然后按第 7 步重新填写密钥。

2. 2

   缺少 App ID、Secret Key 或刷新令牌——回到第 4 步补齐三个值。

3. 3

   Webhook 收不到消息——检查 Webhook URL 是否已在 Zalo 正确粘贴、应用域名是否已验证，以及系统 APP_URL 是否为公网 HTTPS 地址。

6. 需要时重新填写密钥#

Zalo 的刷新令牌只能使用一次，且无法通过 API 重新申请。若刷新链断掉——丢失了一次令牌轮换，或你在 Zalo 侧更换了 Secret Key——请就地更换密钥，无需删除渠道（删除渠道会连同该 OA 的所有会话一起删除）。

1. 1

   在“渠道”中打开 Zalo OA 渠道，滚动到“应用密钥”区域。

2. 2

   重新填写 App ID、Secret Key 和新的刷新令牌（Access token 可留空），然后点击“保存密钥”。

3. 3

   渠道回到“已断开”。点击“连接”验证新密钥。原有会话和消息保持不变。

7. 适用范围与限制#

1. 1

   仅一对一：OA 与每位关注者私下对话，没有群聊。

2. 2

   图片：每张最多 1 MB（JPG/PNG）。更大的图片会被 Zalo 拒绝；ChatHub 会提示你缩小或以文件形式发送。

3. 3

   文件：每个最多 5 MB。更大的文件请以下载链接发送。

4. 4

   无法通过 Zalo OA 消息 API 发送视频；ChatHub 会提前拦截，并建议发送图片、文件或视频链接。

5. 5

   无法拉取历史消息：Zalo OA 没有历史 API，因此渠道只接收连接之后的消息。

6. 6

   OA 没有已读回执，因此收件箱不会显示客户是否已查看消息。

7. 7

   安全签名：Zalo 推送的每个事件都会被 ChatHub 用应用的 Secret Key 校验 X-ZEvent-Signature，因此没有人能伪造消息进入收件箱。

延伸阅读：ChatHub 支持的渠道类型 ↗