Skip to main content
Channels

完成 Channel 配对

使用配对码或待配对记录 ID，为 Channel 消息范围绑定 Identity 和 Template。

POST /api/v1/forward/channel_pairings 仅适用于 identity_resolution.mode=pairing 的 Channel。

请求头

Header是否必填说明
Authorization是Bearer <PAT 或 SAT>
Content-Type是application/json
Idempotency-Key否客户端生成的幂等键，用于安全重试。

请求体参数

参数类型是否必填说明
codestring二选一Channel 消息中显示的有效配对码，与 channel_pairing_id 恰好传一个。
channel_pairing_idstring二选一配对列表 返回的 id。按 ID 管理授权不受配对码过期影响。
identity_idstring是要绑定的 Forward Identity ID。
template_idstring是要绑定的 Forward Template ID。

示例请求

curl -s -X POST 'https://api.qoder.com.cn/api/v1/forward/channel_pairings' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pairing-K7MP92" \
  -d '{
    "code": "K7MP92",
    "identity_id": "idn_019eabc123",
    "template_id": "tmpl_workspace_dev"
  }'
也可按 ID 完成配对，使用相同接口和鉴权： 
{
  "channel_pairing_id": "pair_019eabc123",
  "identity_id": "idn_019eabc123",
  "template_id": "tmpl_workspace_dev"
}

示例响应

HTTP 200 OK 
{
  "id": "pair_019eabc123",
  "type": "channel_pairing",
  "channel_id": "channel_019eabc123",
  "scope_type": "direct",
  "scope_external_id": "external_user_id",
  "scope_display_name": "测试用户",
  "identity_id": "idn_019eabc123",
  "template_id": "tmpl_workspace_dev",
  "status": "active",
  "paired_at": "2026-07-16T10:00:00Z"
}

响应字段

字段类型说明
idstringPairing ID。列表、详情、解除配对使用此值；定时任务 Sink 通过 channel_pairing_id 引用。
typestring固定为 channel_pairing。
channel_idstringChannel ID。
scope_typestring配对范围：direct 私聊用户，room 群聊。
scope_external_idstring范围对应的外部用户或群 ID。
scope_display_namestring用户昵称或群名，未获取到时为空字符串。仅供展示，不作为授权依据。
identity_idstring绑定的 Forward Identity ID。
template_idstring绑定的 Forward Template ID。
statusstring配对成功时为 active。
paired_atstring配对完成时间。

HTTP 错误码

HTTPType触发条件
400invalid_request_error参数缺失、格式非法或含未知字段；配对码无效（含已使用）或过期；Channel 非 pairing 模式。
401authentication_errorPAT 或 SAT 无效或已过期。
403permission_error无调用权限。
404not_found_errorPair、Channel、Identity 或 Template 不存在或不可访问，或 Channel 已归档。
409conflict_error绑定目标冲突、Pair 已解绑、Identity 已停用或并发激活冲突；按 ID 完成配对时 Channel 未启用或未绑定。

注意事项

  • 重试请使用 channel_pairing_id；资源可用且 Pair 未解绑时，相同绑定幂等成功。已使用或过期的配对码不能用于重新配对。
  • 修改绑定请使用更新配对。
  • 配对成功前发送的消息不会自动重放，请重新发送。

相关接口

创建 Channel

解除配对

列出 Channel 配对

获取配对

更新配对