> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 完成 Channel 配对

> 使用 Pairing Code 为 Channel 消息范围绑定 Identity 和 Template。

`POST /api/v1/forward/channel_pairings`

仅适用于 `identity_resolution.mode=pairing` 的 Channel。

## 请求头

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

## 请求体参数

| 参数            | 类型     | 是否必填 | 说明                               |
| ------------- | ------ | ---- | -------------------------------- |
| `code`        | string | 是    | Channel 消息中展示的 6 位 Pairing Code。 |
| `identity_id` | string | 是    | 要绑定的 Forward Identity ID。        |
| `template_id` | string | 是    | 要绑定的 Forward Template ID。        |

## 示例请求

```bash theme={null}
curl -s -X POST 'https://api.qoder.com/api/v1/forward/channel_pairings' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pairing-K7MP92" \
  -d '{
    "code": "K7MP92",
    "identity_id": "idn_019eabc123",
    "template_id": "tmpl_workspace_dev"
  }'
```

## 示例响应

**HTTP 200 OK**

```json theme={null}
{
  "id": "pair_019eabc123",
  "type": "channel_pairing",
  "channel_id": "channel_019eabc123",
  "identity_id": "idn_019eabc123",
  "template_id": "tmpl_workspace_dev",
  "status": "active",
  "paired_at": "2026-07-16T10:00:00Z"
}
```

## 响应字段

| 字段            | 类型     | 说明                       |
| ------------- | ------ | ------------------------ |
| `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 无效或已过期。                                      |
| 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。

## 相关

<CardGroup cols={2}>
  <Card title="创建 Channel" icon="plus" href="/zh/cloud-agents/api/forward/channels/create" />

  <Card title="解除配对" icon="link-slash" href="/zh/cloud-agents/api/forward/channels/unpair-channel" />
</CardGroup>