将 Discord 机器人接入 ChatHub 收件箱

本文解决什么问题#

ChatHub 的 Discord 渠道会接收客户发给机器人的私信，以及服务器文字频道中的消息，客服可以直接在统一收件箱中回复，并支持附件、引用回复、按钮和撤回已发送的消息。

与其他渠道不同，Discord 不通过 webhook 推送消息。ChatHub 会主动与 Discord 建立一条长连接并保持在线，因此这套系统不需要公网 HTTPS 域名：位于 NAT 之后或内网中的服务器同样能收全消息。

Discord 一侧的配置都在开发者后台完成，大约需要十分钟。你需要拥有目标 Discord 服务器的管理权限，因为邀请机器人这一步需要“管理服务器”权限。

1. 开始之前的准备#

1. 1

   一个已验证邮箱的 Discord 账号，用于登录 discord.com/developers/applications 开发者后台。

2. 2

   一个你拥有“管理服务器”权限的 Discord 服务器。如果只是想先试用，可以在 Discord 应用中免费新建一个服务器。

3. 3

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

2. 创建应用与机器人#

1. 1

   打开 discord.com/developers/applications 并登录 Discord 账号。

2. 2

   点击右上角的“新建应用”（New Application）。

3. 3

   在“创建新应用”对话框中填写“名称”——这个名称就是客户看到的机器人名字——勾选同意条款后点击“创建”。

4. 4

   Discord 可能要求验证你不是机器人；完成验证后应用才会创建成功。

5. 5

   在左侧菜单中打开 Bot。新建的应用已自带一个机器人，这个页面用于设置它的头像和显示名称。

3. 获取机器人令牌#

机器人令牌是该渠道唯一的密钥：拿到它的人可以在机器人所在的所有服务器中读取和发送消息。Discord 只在重置后显示一次令牌，所以请立即复制并粘贴到 ChatHub。

1. 1

   仍在 Bot 页面，找到 Token 区域并点击“重置令牌”（Reset Token）。Discord 会要求确认；若账号开启了两步验证，还会要求输入验证码。

2. 2

   复制刚显示出来的令牌。

3. 3

   按本文第 6 步粘贴到 ChatHub 之后再离开页面。如果不慎关闭页面，只需再次重置令牌——旧令牌会在那一刻立即失效。

4. 4

   如果希望只有你才能邀请机器人进入服务器，关闭下方的“公开机器人”（Public Bot）开关并保存。

4. 开启消息内容权限#

Discord 将消息内容视为敏感数据，因此默认情况下机器人只知道有消息，却看不到文字。缺少这一步，渠道仍能连接成功，但收件箱收不到任何消息——ChatHub 会明确写出这个原因。

1. 1

   在 Bot 页面向下滚动到“特权网关意图”（Privileged Gateway Intents）。

2. 2

   打开“消息内容意图”（Message Content Intent）开关。

3. 3

   点击页面底部提示条中的“保存更改”，并等待更新成功的提示。

5. 把机器人邀请进服务器#

机器人只能读取它所在且有权限的频道。这一步会生成一条带有最小权限集合的邀请链接。

1. 1

   在左侧菜单中打开 OAuth2，向下滚动到“OAuth2 URL 生成器”区域。

2. 2

   在“范围”（Scopes）中勾选 bot。

3. 3

   在随即出现的“机器人权限”中，勾选“查看频道”（常规权限列）以及“发送消息”“添加附件”“阅读消息历史”（文字权限列）。

4. 4

   复制页面底部“生成的 URL”中的链接，在浏览器中打开，选择目标服务器并确认授权。

5. 5

   打开 Discord 确认：机器人应当出现在该服务器的成员列表中。

6. 在 ChatHub 中添加 Discord 渠道#

1. 1

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

2. 2

   在对话框的渠道类型一栏中滚动到底部，选择 Discord。

3. 3

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

4. 4

   把机器人令牌粘贴到 Bot token 输入框。ChatHub 会立即校验令牌格式，粘贴不完整时会给出提示。

5. 5

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

6. 6

   点击“连接”。几秒后状态变为“运行中”，渠道名称和头像会被替换成机器人自身的名称与图片。

7. 验证与常见报错#

1. 1

   在 Discord 中，向机器人可见的文字频道发一条消息，或直接私信机器人。

2. 2

   打开 ChatHub 的“消息”页面：新会话会出现，头像角上带有 Discord 标识。

3. 3

   从 ChatHub 回复，并确认消息出现在 Discord 中正确的位置。

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

1. 1

   Discord 拒绝了该机器人令牌——令牌被再次重置，保存的这一份已失效。请获取新令牌并重新创建渠道。

2. 2

   机器人尚未开启消息内容权限——回到第 4 步，打开消息内容意图。

3. 3

   机器人在该频道没有权限——在 Discord 中打开频道设置的“权限”页，为机器人的身份组授予第 5 步列出的权限。

4. 4

   该用户不接收机器人的私信——对方必须与机器人在同一服务器，并在 Discord 隐私设置中允许接收服务器成员的私信。

8. 适用范围与限制#

1. 1

   群聊消息：配置对话框中的“同步群组消息”开关决定服务器文字频道是否进入收件箱。关闭后只保留私信。频道发出第一条消息后，也可以单独排除某个频道。

2. 2

   同步历史消息：只能拉取服务器文字频道中的消息，每个频道最多 200 条，每次最多 500 个频道。历史私信无法拉取，因为 Discord 不允许机器人列出自己的私信列表。

3. 3

   长消息：Discord 单条消息上限为 2000 字符，更长的回复会被 ChatHub 自动拆分成多条连续消息。

4. 4

   附件：未加速的服务器上限为 25 MB。客户发送的文件会在收到时立即复制到 ChatHub 存储，因为 Discord 的附件链接大约一天后就会失效。

5. 5

   提及：ChatHub 发出的消息永远不会触发 @everyone 或 @here，即使正文中包含这些字样。

6. 6

   其他机器人和 webhook 发送的消息不会进入收件箱，以免两个机器人在同一频道里互相回复形成死循环。

7. 7

   Discord 不向机器人提供已读回执，因此收件箱不会显示客户是否已查看消息。

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