# 连接消息通道

将外部消息接收连接关联到指定智能体或团队。先查询当前部署支持的平台、通道类型和接收模式，按所选平台准备凭据，再创建并回读运行状态。

## API 操作

路径相对 Product API Endpoint，使用[调用前准备](../../api-call-basics.md)中的个人访问令牌。

| 方法与路径 | 用途 |
| --- | --- |
| `GET /workspaces/{workspace_id}/ingress-capabilities` | 读取可用平台、通道类型和接收模式。 |
| `GET /workspaces/{workspace_id}/ingress-connections` | 必须同时提供 `target_kind`、`target_workspace_id`、`target_id` 查询同一目标；当前列表不分页。 |
| `POST /workspaces/{workspace_id}/ingress-connections` | 创建入站连接。 |
| `GET /workspaces/{workspace_id}/ingress-connections/{id}` | 读取版本与连接状态。 |
| `PATCH /workspaces/{workspace_id}/ingress-connections/{id}` | 按两项预期版本更新启停、模型或密钥。 |
| `POST /workspaces/{workspace_id}/ingress-connections/{id}/test` | 仅校验 `callback` 连接；JSON 携带当前两项版本，Telegram 另需 callback_url。 |
| `DELETE /workspaces/{workspace_id}/ingress-connections/{id}` | 查询参数携带两项预期版本，删除目标关联；请求体中的版本不生效。 |

## 请求与结果

创建请求包含 `target`（`kind`、`workspace_id`、`id`）、`provider`、`channel_type`、`receive_mode`，以及所选模式的配置。`managed_stream` 放平台凭据；`callback` 或 `mail_polling` 通过 `channel_instance_id` 引用已存在的通道实例，三种配置按模式选择。

完整 Slack JSON 和调用顺序见 CLI [消息通道与插件连接](../../../cli/tasks/channels-plugins.md#cli-message-connections)，Go/Python 示例见 SDK [连接消息通道](../../../sdk/ai-studio/智能体/连接消息通道.md)。

保存响应的连接 `id`、`association_version`、`config_version`。更新和验证使用最近读取的版本。检查 `desired_state`、`observed_state`、`last_receive_at` 和 `last_error_code`，并在外部平台实际发送消息，回查目标智能体或团队的运行及回复。

能力列表列出实现支持的组合，不保证凭据、网络或接收器已就绪。`managed_stream` 创建后由接收器建立连接，通过详情检查状态；不要调用回调专用的 `/test`。回调校验会核验通道配置并启用连接；Telegram 分支会向供应商登记 Webhook，`callback_url` 须为当前部署的完整 HTTPS 地址且路径匹配详情返回的 `callback_path`。校验失败还可能以 HTTP 200 返回 `ok:false` 的通道测试结果，应先检查业务结果，再读取连接。

`managed_stream` 更新时只提交平台允许更新的密钥字段，不重传账号身份：Slack 可更新 app_token/bot_token，飞书为 app_secret，企业微信为 secret。更换 App ID 或 Bot ID 需要按账号关联流程处理。停用后再读取状态；连接建立不等于实际消息已经收发。
