如何在 ChatHub 中添加渠道
连接个人 Zalo、个人 Telegram、Telegram Bot 和网页聊天插件，附创建、认证步骤、网站配置和收件箱验证的截图。
把渠道接入共享收件箱#
渠道页面用于把消息账号和网站聊天接入 ChatHub。本文覆盖全部四种类型：个人 Zalo、个人 Telegram、Telegram Bot 和网页聊天插件，最后介绍连接状态和收件箱验证。
1. 添加渠道前的准备#
- 1
用有渠道管理权限的 ChatHub 账号登录。若页面或操作不可用，请让管理员检查权限。
- 2
个人 Zalo：准备一部已登录目标 Zalo 账号的手机，用来扫码并确认登录。
- 3
个人 Telegram：准备手机号、可接收登录验证码的 Telegram 应用，以及已开启时的两步验证密码。管理员需要先配置共用的 API ID / API Hash。
- 4
Telegram Bot：准备一个由你管理的机器人及其 BotFather token。ChatHub 需要一个 Telegram 能访问到的 HTTPS 地址来接收 webhook；只在本机可用的 DDEV 域名不满足要求。
- 5
网页聊天插件：准备一个你可以修改的网站、允许嵌入聊天的域名，以及面向客户的文案。
2. 打开“添加账号”#
- 1
在你的 ChatHub 域名下打开 /channels，点击右上角的 “Thêm tài khoản”（添加账号）。
- 2
在左侧选择四种类型之一。右侧会说明创建方式和后续步骤。
- 3
Telegram Bot 还需要在此填写 Bot token。其他三种类型在该对话框中不需要填写登录凭据。当前界面会按类型自动命名账号，没有单独的名称字段。
- 4
准备好后点击 “Tạo tài khoản”（创建账号），ChatHub 会打开新账号的配置页。若不想创建，点击 “Huỷ”（取消）或 × 退出。
3. 用二维码添加个人 Zalo#
- 1
选择个人 Zalo → “Tạo tài khoản”。在账号配置中找到 “Đăng nhập Zalo”（Zalo 登录）和 “Quét mã QR”（扫描二维码）。
- 2
点击 “Tạo mã QR”（生成二维码）。用已登录目标账号的手机上的 Zalo 应用扫描它。
- 3
状态变为 “Đã quét”（已扫描）后，在手机上确认登录。等待出现 “Đã kết nối”（已连接），然后检查渠道状态。
- 4
若显示 “Hết hạn”（已过期），点击 “Tạo mã mới”（生成新二维码）重新扫描。若显示 “Bị từ chối”（被拒绝），请检查手机上的确认操作；若显示 “Thất bại”（失败），请阅读错误信息并使用 “Thử lại”（重试）。
4. 添加个人 Telegram#
- 1
先按个人 Telegram 指南完成共用的 API ID / API Hash 配置，然后回到 渠道 → 添加账号 → 个人 Telegram → 创建账号。
- 2
在 “Đăng nhập Telegram” 中填写手机号。国际号码需带 + 和国家代码；点击 “Gửi mã xác thực”（发送验证码）前请核对 “Sẽ gửi mã tới”（验证码将发送至）。
- 3
阅读提示，确认验证码是发到 Telegram 还是短信。把它填入 “Mã xác thực” 并点击 “Xác nhận mã”（确认验证码）。“Gửi lại mã”（重新发送）仅在需要时使用，并遵守 Telegram 的等待时间限制。
- 4
如有提示，请填写两步验证密码并点击 “Xác nhận mật khẩu”。出现“已连接”后，回到渠道列表检查状态，并用一个测试账号验证能否收到消息。
5. 创建并连接 Telegram Bot#
- 1
在 Telegram 中打开已认证的 @BotFather。需要新建机器人时发送 /newbot，按提示设置名称和用户名并获取 token。若使用已有机器人，则用该机器人的 token。
- 2
在 ChatHub 中选择 添加账号 → Telegram Bot。把真实 token 粘贴到 Bot token 并点击创建账号。
- 3
在新建的账号配置中点击 “Kết nối”（连接）。ChatHub 会用已保存的 token 注册 Telegram webhook；创建账号并不能代替这一步。
- 4
等待状态变为“已启用”。用一个测试 Telegram 账号打开该机器人，点击 Start 并发送一条测试消息。在 ChatHub 收件箱中查看，并回复一条以验证双向收发。
6. 创建网站聊天插件#
- 1
选择 添加账号 → 网页聊天插件 → 创建账号。这种类型不需要手机号、二维码或 bot token。
- 2
在配置中点击“连接”以启用聊天窗口。嵌入网站之前先检查其状态。
- 3
找到网站聊天区域的 “Hiển thị”（外观）、“Biểu mẫu”（表单）和 “Mã nhúng”（嵌入代码）三个标签页。按下文完成设置后点击 “Lưu cấu hình”（保存配置）。
7. 自定义外观和问候语#
- 1
在“外观”中选择圆形、胶囊形或竖排标签样式，然后选择靠左/靠右位置和按钮大小。
- 2
调整水平间距、桌面/手机端的底部间距、主色调和图标。带文字的样式还可以修改按钮文案。需要时可从素材库中选择自定义图片。
- 3
填写聊天标题、说明和问候语。例如“示例商店客服”和“你好！需要我们帮你了解哪款产品？”。带默认文案提示的字段可以留空，届时使用系统语言的默认值。
- 4
用预览检查文案和位置。预览只是模拟，仍需在真实网站上测试聊天窗口。问候语只在界面中显示，本身不会创建收件箱会话。
8. 选择会话和附件选项#
- 1
如果希望客户就新问题另开会话，请启用“多会话”：每个会话都会在同一联系人下形成独立的收件箱会话。关闭它则把该客户的消息保持在一个会话里。
- 2
启用图片和文件上传后会出现附件按钮，并支持拖拽上传；当前界面规定单个文件最大 10 MB。
- 3
聊天插件设置就绪后点击“保存配置”。若只是预览，直接关闭对话框不要保存。
9. 在聊天前收集信息#
- 1
打开“表单”，按需启用聊天前信息收集。该表单只会询问一次，回访的访客会直接进入聊天。
- 2
填写引导文字和提交按钮文案，也可以保留默认值。例如：“请告诉我们你的称呼，方便我们更好地为你服务。”
- 3
在要询问的字段中，为姓名、电话或邮箱打开 “Hỏi”（询问）。必填字段再打开 “Bắt buộc”（必填）；未开启询问的字段不能设为必填。
- 4
查看预览并保存配置。提交的信息会写入联系人档案；档案中已有的值不会被覆盖。
10. 把聊天插件嵌入网站#
- 1
打开“嵌入代码”，点击 “Chép mã”（复制代码）复制该渠道的脚本。把它粘贴到需要聊天的每个页面末尾、紧邻 body 结束标签之前，或放进公共页面模板中。
- 2
在允许嵌入的域名中每行填写一个域名。截图中的 https://example.com 是示例，请换成你的网站域名，必要时包含子域名。
- 3
保存配置。打开嵌入后的网站，在电脑和手机上检查聊天按钮、启用了表单时的表单，并用一次测试会话验证消息收发。
- 4
若看不到聊天窗口，请检查渠道是否已连接、脚本位置是否正确、页面域名是否在允许列表中，以及浏览器能否访问你的 ChatHub 服务器。
11. 验证新渠道#
- 1
回到渠道页面并点击刷新图标。若看不到新账号，请清除筛选或按名称/类型搜索。
- 2
把电源开关和状态对照来看：“已启用”表示开关打开且已连接；“已断开”表示当前没有连接；“已关闭”表示开关被关掉。“需要处理”汇总了其他需要检查的状态。
- 3
打开配置可查看登录状态、错误信息、最近信号和支持的能力。已断开的渠道会显示“连接”；其他状态可能显示重新连接、测试和断开。
- 4
认证和连接成功后，用测试账号或访客会话发送一条消息，在收件箱中查看，再回复一条以验证外发。演示渠道上的绿色标记并不能证明与服务商的真实连接。
12. 选择要同步的群组消息#
- 1
对于显示“消息同步”的渠道，请检查群组消息开关。关闭后新的群组消息不会进入收件箱，私聊消息仍会正常接收。
- 2
只有在 ChatHub 收到某个群组的第一条消息之后，该群组才会出现在列表中；列表为空不一定说明连接有问题。
- 3
群组出现后，可按需对每个群组选择忽略或恢复。忽略只会阻止新消息，不会删除已有会话和历史记录。同步开关会立即保存。
13. 问题排查与连接管理#
- 1
找不到渠道：刷新并清除搜索/筛选；重试之前先看清创建账号的结果，避免重复创建。
- 2
收不到个人 Telegram 验证码：核对界面显示的接收对象和发送方式，以及共用 API 配置。验证码无效/过期时需要重新获取；两步验证密码是你自己设置的密码，不是一次性验证码。
- 3
Zalo 已扫码但未连接：检查手机上的确认操作；二维码过期时需要重新生成。
- 4
Telegram Bot token 或 webhook 报错：检查 token 是否正确、连接状态以及公网 HTTPS 地址。服务器错误请交给管理员处理，不要把 token 粘贴到不相关的字段里。
- 5
网站上看得到聊天窗口但收件箱没有消息：问候语和预览不会创建会话。请在嵌入后的网站上填完表单并发送一条测试消息。
- 6
渠道电源开关会立即保存；打开它会尝试连接，但在没有有效会话时可能失败。重新连接/断开会影响真实连接。删除账号不是解决登录问题的常规办法，使用前请仔细阅读确认提示。