# 消息通道与事件回调 API 参考

本页汇总通道实例、连接测试、回调规则和公开回调入口。控制面接口使用 Product API 认证；公开回调入口按第三方 Provider 协议认证，两者不能混用。

## 通道实例接口

| 方法 | 相对路径 | 用途 |
| --- | --- | --- |
| `GET` | `/workspaces/{workspace_id}/channels/{provider}/instances` | 列出通道实例。 |
| `POST` | `/workspaces/{workspace_id}/channels/{provider}/instances` | 创建通道实例。 |
| `POST` | `/workspaces/{workspace_id}/channels/{provider}/instances/test` | 测试尚未保存的配置。 |
| `GET` | `/workspaces/{workspace_id}/channels/{provider}/instances/{instance_id}` | 读取实例详情。 |
| `PATCH` | `/workspaces/{workspace_id}/channels/{provider}/instances/{instance_id}` | 部分更新实例。 |
| `DELETE` | `/workspaces/{workspace_id}/channels/{provider}/instances/{instance_id}` | 停用实例及其凭据。 |
| `POST` | `/workspaces/{workspace_id}/channels/{provider}/instances/{instance_id}/test` | 测试已保存实例。 |

列表支持 `status`、`limit` 和 `offset`。

### 创建和更新字段

| 字段 | 类型 | 必需 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `channel_type` | string | 创建时是 | — | Provider 内的通道类型。 |
| `name` | string | 创建时是 | — | 实例名称。 |
| `description` | string | 否 | — | 实例用途。 |
| `config` | object | 否 | — | 非敏感 Provider 配置。 |
| `secrets` | object | 条件必需 | — | Provider 密钥；只在创建、更新或保存前测试时提交。 |
| `visibility` | string | 否 | — | 可见范围。 |
| `labels` | object | 否 | — | 自定义标签。 |

实例响应包含 `id`、`provider`、`status`、`credential_ref`、可选 `callback_path`、能力、关联工具、非敏感配置和最近测试信息。不会返回明文 Secret。

测试响应的关键字段为 `ok`、`status`、`last_test_status` 和 `last_tested_at`；失败时还可能返回错误码、错误阶段、Provider 错误信息、错误分类和修复建议。

保存前测试接口当前仅支持 `wecom` Provider 的 `wecom_mail` 通道类型。飞书等其他通道类型请先创建实例，再调用实例测试接口。

## 回调规则接口

| 方法 | 相对路径 | 用途 |
| --- | --- | --- |
| `POST` | `/workspaces/{workspace_id}/callback-rules` | 创建回调规则。 |
| `GET` | `/workspaces/{workspace_id}/callback-rules` | 列出回调规则。 |
| `GET` | `/workspaces/{workspace_id}/callback-rules/{rule_id}` | 读取规则。 |
| `PATCH` | `/workspaces/{workspace_id}/callback-rules/{rule_id}` | 部分更新规则。 |
| `DELETE` | `/workspaces/{workspace_id}/callback-rules/{rule_id}` | 删除规则。 |

列表支持 `provider`、`credential_ref`、`enabled`、`limit` 和 `offset`。

| 字段 | 类型 | 必需 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `provider` | string | 创建时是 | — | 事件 Provider。 |
| `credential_ref` | string | 创建时是 | — | 对应通道实例的凭据引用。 |
| `name` | string | 创建时是 | — | 规则名称。 |
| `enabled` | boolean | 否 | — | 是否参与事件匹配。 |
| `priority` | integer | 否 | — | 规则评估顺序。 |
| `match` | object | 否 | — | 资源类型、事件类型、事件动作和字段相等条件。 |
| `target_type` | string | 创建时是 | — | 当前自动化目标使用 `agent_automation_task`。 |
| `target_config` | object | 条件必需 | — | 自动化目标包含 `automation_task_id`。 |
| `stop_after_match` | boolean | 否 | — | 命中后是否停止评估后续规则。 |
| `version` | integer | 更新时是 | — | 当前规则版本，用于并发控制。 |

## 公开回调入口

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| `GET`、`POST` | `/newmoi/callbacks/{provider}/{workspace_id}/{credential_ref}` | 接收 Provider 地址验证或事件。 |

该入口不发送 Product API 的 `X-API-Key`。请求体、查询参数、签名 Header 和响应格式由企业微信、GitHub、飞书或 Slack 协议决定。

## 任务指南

- [配置和测试消息通道](manage-channels.md)
- [接收事件并触发自动化任务](receive-route-events.md)