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 消息中展示的 6 位 Pairing Code。 |
identity_id | string | 是 | 要绑定的 Forward Identity ID。 |
template_id | string | 是 | 要绑定的 Forward Template ID。 |
示例请求
示例响应
HTTP 200 OK
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | Pairing ID，解除配对时使用。 |
type | string | 固定为 channel_pairing。 |
channel_id | string | Channel ID。 |
identity_id | string | 绑定的 Forward Identity ID。 |
template_id | string | 绑定的 Forward Template ID。 |
status | string | 配对成功时为 active。 |
paired_at | string | 配对完成时间。 |
错误码
| HTTP | Type | 触发条件 |
|---|---|---|
| 400 | invalid_request_error | Pairing Code 格式无效、不存在，或 Channel 不是 pairing 模式。 |
| 401 | authentication_error | PAT 或 SAT 无效或已过期。 |
| 404 | not_found_error | Channel、Identity 或 Template 不存在或对当前调用方不可见。 |
| 409 | conflict_error | Pairing Code 已绑定到不同的 Identity 或 Template。 |
注意事项
- 服务端使用 PAT 解析出的
user_id与规范化后的code定位待配对记录——请求中无需传channel_id。 - Pairing Code 在单个用户范围内唯一；响应中返回服务端解析的
channel_id。 - 使用相同 code、相同 Identity 和 Template 重复提交是幂等的，返回已有 Pairing；任何不同的绑定值将返回冲突。
- Channel 是传输连接；Pairing 是该 direct/room scope 的实际执行上下文绑定。
- 配对成功后 Forward 会尽力向原始会话发送成功通知；通知失败不会回滚 Pairing。