IM 渠道接入

前置知识： 先创建好 Bot（Bot 管理），才能为其配置消息渠道。如果你还不了解平台的基本架构，建议先阅读核心概念。

Gateway 是外部 IM 平台与 Monstrum Bot 之间的消息桥梁。配置好 Gateway 后，用户可以直接在 Slack、飞书、Telegram 等常用 IM 中与 Bot 对话，无需进入 Monstrum 管理界面。

概述

Gateway 是什么

Gateway 即”消息渠道”，是 Monstrum 平台对外部 IM 消息通道的统一抽象。每个 Gateway 配置代表一个从外部 IM 平台到平台内某个 Bot 的消息通路。

核心特性：

一 Bot 多渠道 — 同一个 Bot 可以同时接入 Slack、飞书、Telegram 等多个渠道，来自不同渠道的消息都由同一个 Bot 处理
一渠道一 Bot — 每个 Gateway 配置只能关联一个 Bot。如果需要在同一个 IM 平台接入多个 Bot，需创建多个 Gateway
非阻塞投递 — 外部 IM 的 Webhook 请求到达后，平台立即返回 200，消息异步路由到 Bot，Bot 的回复异步投递回 IM 渠道
凭据安全 — IM 平台的 Token、Secret 等凭据在平台内加密存储，列表和详情页中以脱敏形式展示

消息流

用户在 IM 中发送一条消息后，经历如下流转：

用户在 IM 中发消息
    ↓
IM 平台将消息推送到 Monstrum 的 Webhook URL
    ↓
Gateway 适配器验证请求签名、解析消息格式
    ↓
命令拦截（/link、/help 等平台命令直接响应，不经过 Bot）
    ↓
消息策略过滤（回复范围、触发模式、用户/频道白名单等）
    ↓
消息转为内部统一格式（MessageEnvelope），路由到关联的 Bot
    ↓
Bot 处理消息并生成回复
    ↓
Gateway 将回复投递回原 IM 频道

支持的渠道类型

渠道	类型标识	说明
Slack	`slack`	Slack 工作空间，通过 Events API 接收消息
飞书 (Feishu)	`feishu`	飞书/Lark 应用，通过事件订阅接收消息
Telegram	`telegram`	Telegram Bot，支持轮询和 Webhook 两种模式
Discord	`discord`	Discord 服务器 Bot
钉钉 (DingTalk)	`dingtalk`	钉钉企业内部应用机器人
企业微信 (WeCom)	`wecom`	企业微信自建应用，消息加解密
QQ 机器人 (QQBot)	`qqbot`	QQ 开放平台 Bot，支持群聊和私聊
LINE	`line`	LINE Messaging API
WhatsApp	`whatsapp`	WhatsApp Business API
Webhook	`webhook`	通用 Webhook，适用于自定义系统集成

配置流程

消息渠道在每个 Bot 的详情页中配置。

添加渠道

进入目标 Bot 的详情页
切换到 消息渠道 Tab
点击 添加渠道 按钮
选择渠道类型并填写凭据

通用表单字段

所有渠道类型都包含以下通用字段：

字段	说明
名称	渠道的显示名称，如”客服 Slack 频道”、“运维飞书群”
渠道类型	从下拉列表中选择 IM 平台
立即启用	保存后是否立即开始接收消息

选择渠道类型后，表单会动态显示该类型所需的平台凭据字段。

Webhook URL

Gateway 创建成功后，平台会为其生成一个唯一的 Webhook URL，格式为：

https://{你的域名}/gateway/{渠道类型}/{配置 ID}

你需要将此 URL 填入对应 IM 平台的 Webhook/事件订阅配置中，IM 平台才能将消息推送到 Monstrum。

在 Gateway 列表中，点击 Webhook URL 旁的复制按钮即可快速复制。

Slack

通过 Slack Events API，Monstrum 可以接收来自 Slack 工作空间的消息并回复。

前置准备（在 Slack 平台）

创建 Slack App — 访问 Slack API，点击 Create New App > From scratch
配置 Bot Token 权限 — 进入 OAuth & Permissions，在 Bot Token Scopes 中添加：chat:write、app_mentions:read、im:history、im:write，按需添加 channels:history、groups:history
安装到工作空间 — 点击 Install to Workspace，获得 Bot User OAuth Token（以 xoxb- 开头）
获取 Signing Secret — 在 Basic Information > App Credentials 中找到

在 Monstrum 中配置

在添加 Gateway 表单中选择 Slack 类型，填写：

字段	说明
Signing Secret	Slack App 的签名密钥，用于验证来自 Slack 的请求
Bot Token	Bot User OAuth Token，以 `xoxb-` 开头

配置事件订阅

Gateway 创建后，需要将生成的 Webhook URL 填入 Slack App：

在 Slack App 设置页面，进入 Event Subscriptions
开启 Enable Events
在 Request URL 中填入 Monstrum 生成的 Webhook URL
Slack 会发送一个 challenge 请求来验证 URL，Monstrum 会自动响应
验证通过后，在 Subscribe to bot events 中添加：
- message.im — 私聊消息
- app_mention — @Bot 消息
- message.channels — 公共频道消息（可选）
保存更改

消息行为

私聊：用户直接给 Slack Bot 发消息，Bot 直接回复
群聊：默认仅在 @Bot 时回复（由触发模式控制）
线程回复：Bot 会自动在消息线程中回复，保持对话上下文

飞书 (Feishu)

飞书（也称 Lark）通过事件订阅机制接收消息。

前置准备（在飞书平台）

创建应用 — 访问飞书开放平台，进入开发者后台，创建企业自建应用
获取凭据 — 在 凭证与基础信息 页面找到 App ID 和 App Secret
配置事件订阅 — 在 事件与回调 页面获取 Verification Token，后续填入 Webhook URL
配置权限 — 申请 im:message、im:message.group_at_msg、im:message.p2p_msg
发布应用 — 审核发布后权限生效，将应用添加到目标群聊

在 Monstrum 中配置

在添加 Gateway 表单中选择飞书类型，填写：

字段	说明
App ID	飞书应用 App ID
App Secret	飞书应用 App Secret
Verification Token	事件订阅验证 Token，用于验证飞书推送的事件请求

配置事件订阅 URL

Gateway 创建后：

复制 Monstrum 生成的 Webhook URL
在飞书开放平台的 事件与回调 页面，填入此 URL
飞书会发送验证请求，Monstrum 自动响应
在 事件列表 中订阅以下事件：
- im.message.receive_v1 — 接收消息事件

消息行为

私聊：用户在飞书中直接给应用发消息
群聊：将应用添加到群聊后，@应用发送消息
Bot 回复会以应用身份出现在对话中

通过 Telegram Bot API 接收和回复消息。

前置准备（在 Telegram 中）

创建 Bot — 在 Telegram 中搜索 @BotFather，发送 /newbot，按提示操作后获得 Bot Token
配置 Bot 属性（可选） — 通过 BotFather 的 /setdescription、/setuserpic、/setcommands 等命令自定义 Bot 信息
群聊设置（如需要） — /setjoingroups 允许加入群聊，/setprivacy 关闭 Privacy Mode 以接收所有群聊消息

在 Monstrum 中配置

在添加 Gateway 表单中选择 Telegram 类型，填写：

字段	说明
Bot Token	从 @BotFather 获取的 Token
代理（可选）	HTTP 代理地址，如 `http://127.0.0.1:7890`，用于网络受限环境

连接模式

Telegram 适配器默认使用 长轮询（Polling） 模式主动拉取消息，无需配置 Webhook URL。平台启动后自动开始轮询。

如果你的部署环境有公网可达的地址，也可以使用 Webhook 模式获得更低的消息延迟。

消息行为

私聊：用户直接给 Bot 发消息，Bot 直接回复
群聊：需要将 Bot 添加到群组中。默认需要 @Bot 才会响应（可通过关闭 Privacy Mode 接收所有消息）
Bot 支持回复特定消息（Reply），保持上下文关联

Discord

面向社区的即时通讯平台，广泛用于游戏和开发者社区。

前置准备（在 Discord 平台）

创建应用 — 访问 Discord Developer Portal，创建新应用
创建 Bot — 在 Bot 页面点击 Add Bot，开启 Message Content Intent（必须），复制 Bot Token
邀请 Bot 到服务器 — 在 OAuth2 > URL Generator 中选择 bot scope，勾选 Send Messages、Read Message History、View Channels 权限，使用生成的链接邀请

在 Monstrum 中配置

在添加 Gateway 表单中选择 Discord 类型，填写：

字段	说明
Discord Bot Token	从 Developer Portal 获取的 Bot Token
允许的服务器 ID（可选）	限制 Bot 只在指定服务器中工作，逗号分隔多个 ID

如果不填写允许的服务器 ID，Bot 将在所有已加入的服务器中响应消息。

获取服务器 ID

在 Discord 中，开启 开发者模式（用户设置 > 高级 > 开发者模式），然后右键点击服务器图标，选择 复制服务器 ID。

消息行为

私聊：用户可以直接给 Bot 发私信
服务器频道：Bot 在被允许的频道中接收消息
默认仅在 @Bot 时回复（可通过触发模式调整）

钉钉 (DingTalk)

阿里巴巴出品的企业协作平台，在国内企业中广泛使用。

前置准备（在钉钉平台）

创建应用 — 访问钉钉开放平台，创建企业内部 机器人 类型应用
获取凭据 — 在 基础信息 页面找到 AppKey（ClientID）和 AppSecret（ClientSecret）
配置机器人 — 在 机器人与消息推送 页面开启功能，后续填入 Webhook URL
发布应用 — 申请权限后，创建发布版本提交审核

在 Monstrum 中配置

在添加 Gateway 表单中选择钉钉类型，填写：

字段	说明
应用 AppKey	钉钉应用的 AppKey（ClientID）
应用 AppSecret	钉钉应用的 AppSecret（ClientSecret）

配置消息接收地址

Gateway 创建后：

复制 Monstrum 生成的 Webhook URL
在钉钉开放平台的 机器人与消息推送 页面，填入此 URL
钉钉会通过此 URL 推送用户发送给机器人的消息

消息行为

单聊：用户直接给机器人发消息
群聊：将机器人添加到群聊后，@机器人发送消息
钉钉平台使用签名验证确保消息来源安全

企业微信 (WeCom)

腾讯出品的企业通讯平台。消息收发使用 AES-256-CBC 加解密，安全性较高。

前置准备（在企业微信平台）

创建自建应用 — 登录企业微信管理后台，进入 应用管理 > 自建 创建应用
获取凭据 — CorpID（我的企业页面底部）、AgentID 和 Secret（应用详情页）
配置接收消息 — 在应用的 接收消息 中设置 URL（填 Webhook URL），系统自动生成 Token 和 EncodingAESKey，记录备用
配置可信域名 — 如需要，在应用设置中添加 Monstrum 域名

在 Monstrum 中配置

在添加 Gateway 表单中选择 企业微信 类型，填写：

字段	说明
企业 ID (CorpID)	企业的唯一标识
应用 AgentID	自建应用的 AgentID
应用 Secret	应用的密钥
回调 Token	接收消息配置中生成的 Token
EncodingAESKey	接收消息配置中生成的消息加解密密钥

消息加解密

企业微信的消息传输使用 AES-256-CBC 加密：

加密密钥由 EncodingAESKey 派生
消息中嵌入 CorpID 用于校验来源
Monstrum 自动处理加解密，无需用户手动操作

消息行为

单聊：用户在企业微信中给应用发消息
群聊：将应用添加到群聊后，@应用发送消息
所有消息在传输过程中加密，确保企业数据安全

QQ 机器人 (QQBot)

基于 QQ 开放平台，支持在 QQ 群和私聊中提供 AI 服务。

前置准备（在 QQ 开放平台）

创建应用 — 访问 QQ 开放平台，创建机器人应用
获取凭据 — 记录 AppID 和 AppSecret
配置事件订阅 — 在 开发设置 中配置消息接收 URL，后续填入 Webhook URL
沙箱环境（可选） — 开发阶段可使用沙箱环境测试

在 Monstrum 中配置

在添加 Gateway 表单中选择 QQ 机器人 类型，填写：

字段	说明
App ID	QQ 开放平台的应用 AppID
App Secret	应用 AppSecret

验证机制

QQ 开放平台使用 Ed25519 签名验证：

平台自动使用 AppSecret 派生 Ed25519 密钥对
验证请求时，URL 验证事件 (op=13) 会自动返回签名后的 challenge
此过程完全自动，无需用户参与

消息行为

群聊：用户在群内 @机器人发送消息，事件类型为 GROUP_AT_MESSAGE_CREATE
私聊：用户直接给机器人发消息，事件类型为 C2C_MESSAGE_CREATE
QQ 机器人使用 OpenID 体系标识用户和群组

LINE

在日本、东南亚等地区广泛使用的即时通讯平台。

前置准备（在 LINE 平台）

创建 Channel — 访问 LINE Developers Console，创建 Provider，然后创建 Messaging API 类型的 Channel
获取凭据 — Channel Access Token（Messaging API Tab 中生成）和 Channel Secret（Basic settings Tab）
配置 Webhook — 在 Messaging API Tab 中开启 Use webhook，后续填入 Webhook URL
关闭自动回复（建议） — 在 LINE Official Account Manager 中关闭自动应答消息

在 Monstrum 中配置

在添加 Gateway 表单中选择 LINE 类型，填写：

字段	说明
Channel Access Token	Messaging API 的长期访问令牌
Channel Secret	Channel 的密钥，用于验证 Webhook 请求签名

消息行为

一对一聊天：用户添加官方账号为好友后直接发消息
群聊：将官方账号添加到群组中后可以接收消息
LINE 使用 Webhook 模式，需要公网可达的 URL

通过 WhatsApp Business API 实现消息收发。

前置准备（在 Meta 平台）

创建应用 — 访问 Meta for Developers，创建 Business 类型应用，添加 WhatsApp 产品
获取凭据 — Access Token（API 设置中生成永久令牌）、电话号码 ID（商业号码 ID）、App Secret（可选，基本设置中）
配置 Webhook — 在 WhatsApp Webhook 设置中填入 Webhook URL，设置自定义 Verify Token（需与 Monstrum 一致），订阅 messages 字段

在 Monstrum 中配置

在添加 Gateway 表单中选择 WhatsApp 类型，填写：

字段	说明
访问令牌 (Access Token)	WhatsApp Business API 的永久访问令牌
电话号码 ID	WhatsApp 商业号码的 ID
验证令牌 (Verify Token)	Webhook 验证令牌，需与 Meta 平台中设置的一致
App Secret（可选）	Meta 应用密钥，用于验证 Webhook 请求签名。建议填写以增强安全性

Webhook 验证

WhatsApp 的 Webhook 验证分两步：

GET 验证 — Meta 发送 GET 请求到 Webhook URL，携带 hub.mode=subscribe 和 hub.verify_token 参数。Monstrum 自动验证 Verify Token 并返回 hub.challenge
POST 推送 — 验证通过后，消息通过 POST 推送到同一 URL

消息行为

WhatsApp 仅支持一对一私聊，不支持群聊中的 Bot
用户给 WhatsApp 商业号码发消息即可触发 Bot 回复
注意 WhatsApp 的 24 小时对话窗口规则：用户发消息后 24 小时内可以自由回复，超时需使用模板消息

Webhook（通用）

Webhook 是最灵活的接入方式，适用于自定义系统集成。你可以从任何能发送 HTTP 请求的系统向 Monstrum 推送消息。

适用于内部系统集成（监控告警、工单、CI/CD）、自定义 IM 接入、API 自动化调用和开发调试。

在 Monstrum 中配置

在添加 Gateway 表单中选择 Webhook 类型，填写：

字段	说明
名称	资源名称，如”监控告警通道”
关联 Bot	选择处理消息的 Bot
回调 URL（可选）	Bot 回复发送到此 URL。如不填，回复仅记录在平台内
签名密钥（可选）	用于验证请求签名。如填写，每次请求需携带 `X-Webhook-Secret` 头

发送消息到 Webhook

创建 Gateway 后，获取生成的 Webhook URL，向此 URL 发送 POST 请求：

请求格式：

字段	类型	必填	说明
`source`	string	否	消息来源标识，默认为 `webhook`
`user_id`	string	是	用户 ID
`channel_id`	string	否	频道/群聊 ID
`text`	string	是	消息文本
`callback_url`	string	否	单次请求的回调地址（覆盖 Gateway 配置的回调 URL）
`metadata`	object	否	额外元数据

签名验证

如果配置了签名密钥，发送请求时需在 HTTP Header 中携带：

X-Webhook-Secret: {你配置的签名密钥}

未携带或不匹配时，请求将被拒绝。

回复投递

Bot 的回复会通过 HTTP POST 异步发送到配置的回调 URL。如果单次请求中也提供了 callback_url，则优先使用请求中的地址。

消息策略

消息策略用于精细控制 Bot 在 IM 渠道中的响应行为。在 Gateway 管理页面或 Bot 详情页的消息渠道 Tab 中，点击某个 Gateway 的管理按钮，即可配置消息策略。

回复范围

控制 Bot 响应哪些类型的会话：

选项	说明
全部	私聊和群聊消息都回复（默认）
仅私聊	只回复私聊消息，群聊中的消息静默忽略
仅群聊	只回复群聊消息，私聊消息静默忽略

面向内部团队的 Bot 通常设为全部；群聊专用 Bot 设为 仅群聊；处理敏感信息的 Bot 设为 仅私聊。

触发模式

控制 Bot 在什么条件下响应消息：

选项	说明
智能	群聊中仅 @Bot 时回复，私聊中所有消息都回复（默认，推荐）
所有消息	无论是否 @Bot，所有消息都回复
仅 @Bot	只有明确 @Bot 的消息才回复，包括私聊

大多数场景使用智能模式即可。专属频道（仅与 Bot 交互）可设为 所有消息；多人群组建议 仅 @Bot 避免误触发。

用户过滤

通过白名单和黑名单控制哪些用户可以与 Bot 交互：

配置	说明
允许的用户	用户 ID 白名单。如果填写了，只有列表中的用户消息才会被处理
屏蔽的用户	用户 ID 黑名单。列表中的用户消息会被静默忽略

白名单和黑名单使用 IM 平台的用户 ID（非用户名）
白名单为空表示不做白名单限制（所有用户都允许）
黑名单优先级高于白名单

频道过滤

通过白名单和黑名单控制 Bot 响应哪些频道的消息：

配置	说明
允许的频道	频道 ID 白名单。如果填写了，只有列表中的频道消息才会被处理
屏蔽的频道	频道 ID 黑名单。列表中的频道消息会被静默忽略

使用 IM 平台的频道/群组 ID
白名单为空表示不做白名单限制
适用于 Bot 加入了多个频道但只需要在特定频道工作的场景

策略生效顺序

消息策略按以下顺序依次检查，任何一步不通过即静默忽略：

回复范围 — 会话类型是否匹配
触发模式 — 是否满足触发条件
用户白名单 — 用户是否在允许列表中（如有配置）
用户黑名单 — 用户是否在屏蔽列表中
频道白名单 — 频道是否在允许列表中（如有配置）
频道黑名单 — 频道是否在屏蔽列表中

管理员绑定

每个 Gateway 支持绑定一名 IM 管理员。管理员可以在 IM 中直接使用平台管理命令，无需登录 Monstrum 管理界面。

绑定流程

在 Monstrum 管理界面中，找到目标 Gateway
在 管理员绑定 区域，点击 重新生成绑定码
系统生成一个一次性绑定码
将绑定码告知需要成为管理员的 IM 用户
该用户在 IM 中通过私聊向 Bot 发送：

/link {绑定码}

绑定成功后，系统回复”Admin linked successfully!”
绑定码使用后自动失效，不可重复使用

管理员权限

绑定管理员后，该用户可以在 IM 中使用以下管理命令：

命令	说明	权限要求
`/link {code}`	绑定为管理员	所有用户，仅私聊
`/unlink`	解除管理员绑定	管理员，仅私聊
`/status`	查看 Bot 状态和策略信息	管理员，仅私聊
`/chathis on\|off\|clear`	管理频道会话持久化	管理员，私聊和群聊
`/help`	显示可用命令列表	所有用户，私聊和群聊

命令说明

/status

查看当前 Gateway 的状态信息，包括：

关联的 Bot 名称
Gateway 渠道类型
管理员绑定状态
当前消息策略配置

/chathis（会话持久化管理）

管理当前频道的会话持久化功能：

/chathis on — 开启会话持久化，Bot 会记住频道中的对话历史
/chathis off — 关闭会话持久化，每次对话都是全新的
/chathis clear — 清除当前频道的对话历史，但不改变持久化开关状态

此命令可以在群聊中使用，作用于当前所在的频道。

/help

显示所有可用命令的列表，包括平台内置命令和 Bot 绑定的工作流命令。如果 Bot 关联了支持 IM 命令触发的工作流，这些命令也会在 /help 中列出。

注意事项

每个 Gateway 同一时间只能有一名管理员
绑定码一次性使用，使用后或重新生成后旧码失效
管理命令（除 /link 和 /help 外）只有管理员才能执行
/link 和 /unlink 只能在私聊中使用，防止绑定码泄露
/help 和 /chathis 可以在群聊中使用

Gateway 状态管理

状态说明

状态	说明
已连接	Gateway 正常工作，能够接收和发送消息
未连接	Gateway 已创建但尚未收到过消息，或适配器未启动
错误	Gateway 出现异常，如凭据无效、连接断开等

启用、编辑与删除

启用/禁用 — 在列表中通过开关控制。禁用不删除配置，重新启用即恢复
编辑 — 点击编辑按钮修改配置。凭据字段留空则保持原值不变
删除 — 不可逆操作。删除后 IM 用户无法再与 Bot 交互，IM 平台侧的 Webhook 配置需手动移除

与 Bot 的对话交互

通过 Gateway 接入的消息会进入 Bot 的会话系统，详细说明请参考对话交互。这里简要说明 IM 渠道相关的特性：

会话隔离 — 不同 IM 频道的消息属于不同会话；同一频道中不同用户的消息属于同一会话（群聊场景）
会话持久化 — 会话空闲 30 分钟后过期。管理员可通过 /chathis on 开启持久化，过期后自动保存对话历史，下次对话恢复上下文。超过 80 条消息时自动压缩（LLM 总结旧消息，保留近期对话）
去重机制 — 平台内置去重，即使 IM 平台因网络抖动多次推送同一消息，Bot 也只处理一次

常见问题

Gateway 状态显示”未连接”

可能原因：

Gateway 刚创建，尚未收到过来自 IM 平台的消息
IM 平台的 Webhook URL 配置不正确
平台凭据（Token、Secret 等）填写有误
网络问题导致 IM 平台无法访问 Monstrum 的 Webhook URL

排查步骤：

检查 Monstrum 是否可以从公网访问（IM 平台需要能够发送 HTTP 请求到 Webhook URL）
确认 Webhook URL 已正确填入 IM 平台的配置中
检查凭据是否正确（可以编辑 Gateway 重新填写）
查看 IM 平台侧的 Webhook 日志是否有错误提示

Bot 不回复 IM 消息

可能原因：

Gateway 未启用
消息策略的触发模式限制了响应
用户不在白名单中，或被加入了黑名单
频道不在白名单中，或被加入了黑名单
关联的 Bot 存在配置问题（如未配置 LLM 提供商）

排查步骤：

确认 Gateway 处于启用状态
检查消息策略的回复范围和触发模式设置
检查用户和频道过滤列表
在 Monstrum 管理界面直接与 Bot 对话，确认 Bot 本身工作正常
查看 Bot 的执行历史，确认是否收到了消息

消息重复回复

平台内置去重机制，正常情况下不会重复。检查是否存在多个 Gateway 指向同一频道，或 IM 平台是否重复推送了 Webhook。

特定渠道验证失败

Slack URL verification failed — 确认 Monstrum 服务运行中、公网可达，Signing Secret 填写正确
飞书事件推送不到 — 确认 Verification Token 一致，已订阅 im.message.receive_v1 事件，应用已发布
企业微信消息解密失败 — 确认 EncodingAESKey（注意无多余空格）和 CorpID 正确
WhatsApp Webhook 验证失败 — 确认 Verify Token 一致，Webhook URL 可通过 GET 访问

最佳实践

始终配置签名验证 — Webhook 类型务必设置签名密钥，其他类型确保凭据完整填写
使用用户白名单 — Bot 只服务特定用户时，配置允许的用户列表
限制服务器/频道 — Discord 等平台配置允许的服务器 ID，缩小 Bot 工作范围
先测试再上线 — 创建 Gateway 后先在测试频道验证消息收发
使用智能触发 — 默认模式适合大多数场景，群聊不过度干扰
按需启用 — 暂不需要的渠道禁用而非删除，便于恢复
描述性命名 — 包含用途和平台，如”客服 Slack 频道”、“飞书 - 研发群”、“Webhook (测试)”

在 GitHub 上编辑此页