消息渠道接入
将 Agent 接入外部消息平台时，需要配置平台授权、消息路由、应用或机器人权限及凭据。
打开控制台 → 触发配置 → 新建触发配置，即可查看当前 AstraBox 部署中已安装的消息平台。每个已安装的适配器都会提供对应的设置入口和配置字段。
| 层级 | 职责 |
|---|---|
| 消息平台 | 管理应用或机器人身份、权限设置和事件订阅。 |
| 消息平台适配器 | 维持消息产品连接，并把连接状态、消息和事件转换为统一协议。 |
| AstraBox | AstraBox 保存消息平台触发配置及其只写凭据，将每个外部会话映射到 Session，并记录任务处理与回复投递状态。 |
平台授权与消息路由
AstraBox 的消息平台触发配置有两个独立的配置维度：
| 维度 | 解决的问题 | 配置方式 |
|---|---|---|
| 平台授权 | 应用或机器人如何获得收发消息的权限。 | 消息平台提供的凭据和设置。 |
| 消息路由 | 某条上行消息应使用哪个 Agent 和 Session。 | 触发配置选定的 Agent，以及平台提供的外部会话。 |
消息平台凭据用于授权应用或机器人连接，不会把消息参与者认证为 AstraBox 用户。已接收的消息会以触发配置所选 Agent 的所有者身份运行，因此应按目标用户范围设置机器人的可见性和平台权限。
接入消息平台
所有已安装的消息平台都采用相同流程：
- 创建触发配置： 打开控制台 → 触发配置 → 新建触发配置，选择 Agent，再选择消息平台。
- 创建应用或机器人： 使用 AstraBox 表单链接的官方开发者控制台。
- 配置权限和事件： 允许应用或机器人接收目标消息并发送回复。按照平台要求选择长连接或 Webhook 等连接方式。
- 填写凭据： 完成 AstraBox 显示的字段并创建触发配置。字段由已安装的适配器定义，凭据只允许写入。
- 按页面提示完成回调配置： 如果触发配置详情页显示回调地址，将其复制到消息平台的事件或 Webhook 设置中。把应用或机器人加入目标会话，然后发送消息。
使用回调的接入方式依赖创建触发配置时显示的 AstraBox 公网地址。如果该地址发生变化，请先在消息平台中更新回调地址，再继续接收消息。
消息路由
固定 Agent
每个消息平台触发配置都属于一个 Agent。该触发配置接收的所有上行消息都由所选 Agent 处理。
会话映射
平台授权完成后，消息路由流程如下：
- 用户在私聊、群组、频道或话题中发送消息。
- 适配器验证并规范化平台事件。
- AstraBox 持久记录这条平台消息，避免重复投递导致 Agent 执行两次。
- 稳定的外部会话标识用于为所选 Agent 创建或复用 Session。
- Agent 处理消息，AstraBox 记录向消息平台投递回复的结果。
私聊、群组、频道和话题使用消息平台提供的稳定标识。这些标识与 AstraBox 的身份认证和资源所有权相互独立。
消息平台触发配置绑定的 Agent 创建后不能更换。如需将平台连接交给另一个 Agent，请创建新的触发配置。
凭据接入
在对应开发者平台创建应用或机器人、配置必要权限并取得凭据，然后在新建触发配置中填写。所选适配器会提供准确的非敏感设置和只写凭据字段。
凭据只在创建或更新消息平台触发配置时写入，绝不会明文回显。替换凭据时，会替换该适配器要求的完整凭据集合。
配置应用或机器人
创建应用或机器人
从 AstraBox 表单打开官方开发者控制台。创建应用或机器人，并为这个消息平台触发配置分配独立身份。
配置权限和事件
只授予 Agent 处理目标会话所需的消息和事件权限。启用平台要求的事件订阅和连接方式。
发布或启用应用
按照消息平台要求发布或启用应用。将可见范围设为目标组织、工作区、群组或用户，再把机器人加入需要接收消息的位置。
获取凭据
复制 AstraBox 表单要求的凭据。对于使用回调的连接，请先创建触发配置，再登记详情页显示的回调地址。