POST /api/v1/forward/channels
创建外部消息平台的 Channel 实例，用于接收外部 IM 上行消息并发送回复。
请求头
| Header | 是否必填 | 说明 |
|---|---|---|
| Authorization | 是 | Bearer <PAT 或 SAT> |
| Content-Type | 是 | application/json |
| Idempotency-Key | 否 | 有副作用请求可选的幂等键。 |
请求体参数
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| identity_id | string | 条件必填 | fixed 模式必填；pairing 模式不传。 |
| identity_resolution.mode | string | 否 | Identity 解析模式：fixed（默认）或 pairing。 |
| template_id | string | 条件必填 | fixed 模式必填；pairing 模式不传。 |
| channel_type | string | 是 | 渠道类型，当前支持 wechat、wecom、feishu、dingtalk。 |
| name | string | 否 | Channel 展示名。 |
| enabled | boolean | 否 | 人工启停开关，默认 true。传 false 可创建后暂不处理上行消息。 |
| channel_config.credentials | object | 条件必填 | 渠道运行凭据。扫码授权类渠道可省略；直连凭据类渠道按 channel_type 传入：feishu 为 app_id/app_secret，dingtalk 为 client_id/client_secret，wecom 为 bot_id/secret。凭据不明文回显。 |
| channel_config.response_options | object | 否 | 回复内容可见性配置。 |
示例请求
pairing 模式只创建渠道连接，不在创建时指定 Identity 或 Template：
示例响应
HTTP 201 Created
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | Channel ID，示例前缀 channel_。 |
| type | string | 固定为 channel。 |
| identity_id | string|null | fixed 模式为绑定的 Forward Identity ID；pairing 模式为 null。 |
| identity_resolution.mode | string | Identity 解析模式：fixed 或 pairing。 |
| template_id | string|null | fixed 模式为绑定的 Forward Template ID；pairing 模式为 null。 |
| channel_type | string | 外部渠道类型。 |
| enabled | boolean | 人工启停开关。 |
| binding_status | string | unbound、bound 或 expired。 |
错误码
| HTTP | Type | 触发条件 |
|---|---|---|
| 400 | invalid_request_error | 渠道类型不支持。 |
| 400 | invalid_request_error | Identity 解析模式与 identity_id/template_id 组合不匹配。 |
| 400 | invalid_request_error | 缺少必要凭据。 |
| 401 | authentication_error | PAT 或 SAT 无效或已过期。 |
| 403 | permission_error | 渠道数量超出配额上限。 |
| 404 | not_found_error | Template 不存在或不可见。 |
| 404 | not_found_error | Identity 不存在或不可见。 |
| 409 | conflict_error | Identity 已停用。 |
| 409 | conflict_error | 凭证校验冲突。 |
| 502 | api_error | 渠道服务不可用。 |
注意事项
enabled为可选入参，默认true；传false可在绑定完成前暂不启用。- 只有
enabled=true且binding_status=bound时才可处理上行消息。 - 如果只是临时停止处理上行消息，优先使用 Update Channel 设置
enabled=false。 fixed模式始终使用创建时指定的 Identity 和 Template。pairing模式下 Channel 仅表示传输连接，Identity 和 Template 由 Pairing API 按消息范围绑定。- Identity 解析模式创建后不可修改。