> ## 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 のペアリング

> ペアリングコードを使用して、Channel メッセージスコープに Identity と Template をバインドします。

`POST /api/v1/forward/channel_pairings`

`identity_resolution.mode=pairing` の Channel にのみ適用されます。

## Headers

| Header            | Required | Description                 |
| ----------------- | -------- | --------------------------- |
| `Authorization`   | Yes      | `Bearer <PAT>`              |
| `Content-Type`    | Yes      | `application/json`          |
| `Idempotency-Key` | No       | 安全なリトライのためのクライアント生成のべき等性キー。 |

## Body parameters

| Parameter     | Type   | Required | Description                       |
| ------------- | ------ | -------- | --------------------------------- |
| `code`        | string | Yes      | Channel メッセージに表示された 6 桁のペアリングコード。 |
| `identity_id` | string | Yes      | バインドする Forward Identity ID。       |
| `template_id` | string | Yes      | バインドする Forward Template ID。       |

## Example request

```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"
  }'
```

## Example response

**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"
}
```

## Response fields

| Field         | Type   | Description                  |
| ------------- | ------ | ---------------------------- |
| `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 | ペアリング完了時刻。                   |

## Error codes

| HTTP | Type                    | Trigger                                                  |
| ---- | ----------------------- | -------------------------------------------------------- |
| 400  | `invalid_request_error` | ペアリングコードの形式が無効、存在しない、または Channel が `pairing` モードではありません。 |
| 401  | `authentication_error`  | PAT が無効または期限切れです。                                        |
| 404  | `not_found_error`       | Channel、Identity、または Template が存在しないか、呼び出し元から参照できません。    |
| 409  | `conflict_error`        | ペアリングコードが既に別の Identity または Template にバインドされています。         |

## Notes

* サーバーは PAT から解決した `user_id` と正規化した `code` を使ってペンディング中のペアリングレコードを特定します。リクエストに `channel_id` は不要です。
* ペアリングコードは単一ユーザースコープ内で一意です。レスポンスにはサーバーが解決した `channel_id` が返されます。
* 同じコードを同じ Identity と Template で送信するとべき等で、既存の Pairing を返します。異なるバインディング値の場合はコンフリクトを返します。
* Channel はトランスポート接続であり、Pairing はその direct/room スコープの実際の実行コンテキストバインディングです。
* ペアリング成功後、Forward は元の会話に成功通知をベストエフォートで送信します。通知の失敗により Pairing がロールバックされることはありません。

## Related

<CardGroup cols={2}>
  <Card title="Channel の作成" icon="plus" href="/ja/cloud-agents/api/forward/channels/create" />

  <Card title="Channel のペアリング解除" icon="link-slash" href="/ja/cloud-agents/api/forward/channels/unpair-channel" />
</CardGroup>