使用配对码或待配对记录 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 | 否 | 客户端生成的幂等键，用于安全重试。 |
请求体参数
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
code | string | 二选一 | Channel 消息中显示的有效配对码，与 channel_pairing_id 恰好传一个。 |
channel_pairing_id | string | 二选一 | 配对列表 返回的 id。按 ID 管理授权不受配对码过期影响。 |
identity_id | string | 是 | 要绑定的 Forward Identity ID。 |
template_id | string | 是 | 要绑定的 Forward Template ID。 |
示例请求
示例响应
HTTP 200 OK
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | Pairing ID。列表、详情、解除配对使用此值；定时任务 Sink 通过 channel_pairing_id 引用。 |
type | string | 固定为 channel_pairing。 |
channel_id | string | Channel ID。 |
scope_type | string | 配对范围：direct 私聊用户，room 群聊。 |
scope_external_id | string | 范围对应的外部用户或群 ID。 |
scope_display_name | string | 用户昵称或群名，未获取到时为空字符串。仅供展示，不作为授权依据。 |
identity_id | string | 绑定的 Forward Identity ID。 |
template_id | string | 绑定的 Forward Template ID。 |
status | string | 配对成功时为 active。 |
paired_at | string | 配对完成时间。 |
错误码
| HTTP | Type | 触发条件 |
|---|---|---|
| 400 | invalid_request_error | code 与 channel_pairing_id 未满足二选一、配对码无效/过期，或 Channel 不是 pairing 模式。 |
| 401 | authentication_error | PAT 或 SAT 无效或已过期。 |
| 404 | not_found_error | Pair、Channel、Identity 或 Template 不存在或当前调用方不可见。 |
| 409 | conflict_error | Pair 已绑定到其他 Identity/Template，或已解绑。 |
注意事项
- 调用方须具备对应 Channel 的管理权限。
- 重复绑定相同 Identity、Template 会返回成功；修改已有绑定请使用更新配对。
- 配对码已使用但绑定未完成时，可从配对列表获取 Pair ID 后重试。
- 配对成功前发送的消息不会自动重放，请重新发送。