POST /api/v1/forward/channels
创建外部消息平台的 Channel 实例，用于接收外部 IM 上行消息并发送回复。
请求头
| Header | 是否必填 | 说明 |
|---|---|---|
| Authorization | 是 | Bearer <PAT> |
| Content-Type | 是 | application/json |
| Idempotency-Key | 否 | 有副作用请求可选的幂等键。 |
请求体参数
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| identity_id | string | 是 | Forward Identity ID，必须属于当前调用方且已启用。 |
| template_id | string | 是 | 收到消息并创建 Session 时使用的 Forward Template ID。 |
| 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 | 否 | 回复内容可见性配置。 |
示例请求
curl -s -X POST 'https://api.qoder.com/api/v1/forward/channels' \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{
"identity_id": "idn_019eabc123",
"template_id": "tmpl_support",
"channel_type": "feishu",
"name": "Support Feishu channel",
"enabled": true,
"channel_config": {
"credentials": {
"app_id": "...",
"app_secret": "..."
},
"response_options": {
"include_tool_calls": false,
"include_thinking": false
}
}
}'
示例响应
HTTP 201 Created{
"id": "channel_019eabc123",
"type": "channel",
"identity_id": "idn_019eabc123",
"template_id": "tmpl_support",
"channel_type": "feishu",
"name": "Support Feishu channel",
"enabled": true,
"binding_status": "bound",
"channel_config": {
"response_options": {
"include_tool_calls": false,
"include_thinking": false
}
},
"created_at": "2026-06-18T10:00:00Z",
"updated_at": "2026-06-18T10:00:00Z"
}
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | Channel ID，示例前缀 channel_。 |
| type | string | 固定为 channel。 |
| identity_id | string | 绑定的 Forward Identity ID。 |
| template_id | string | 绑定的 Forward Template ID。 |
| channel_type | string | 外部渠道类型。 |
| enabled | boolean | 人工启停开关。 |
| binding_status | string | unbound、bound 或 expired。 |
错误码
| HTTP | Type | 触发条件 |
|---|---|---|
| 400 | invalid_request_error | 渠道类型不支持。 |
| 400 | invalid_request_error | 缺少必要凭据。 |
| 401 | authentication_error | PAT 无效或已过期。 |
| 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。