Skip to main content
Channels

Pair a channel

Use a pairing code or pending pairing record ID to bind an Identity and Template to a Channel message scope.

POST /api/v1/forward/channel_pairings Only applicable to Channels with identity_resolution.mode=pairing.

Headers

HeaderRequiredDescription
AuthorizationYesBearer <PAT or SAT>
Content-TypeYesapplication/json
Idempotency-KeyNoClient-generated unique idempotency key for safe retries.

Body parameters

ParameterTypeRequiredDescription
codestringOne of twoValid pairing code displayed in the Channel message. Provide exactly one of code and channel_pairing_id.
channel_pairing_idstringOne of twoThe id returned by List channel pairings. Authorization by ID is unaffected by pairing code expiration.
identity_idstringYesForward Identity ID to bind.
template_idstringYesForward Template ID to bind.

Example request

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"
  }'
You can also complete pairing by ID using the same endpoint and authentication: 
{
  "channel_pairing_id": "pair_019eabc123",
  "identity_id": "idn_019eabc123",
  "template_id": "tmpl_workspace_dev"
}

Example response

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": "Test user",
  "identity_id": "idn_019eabc123",
  "template_id": "tmpl_workspace_dev",
  "status": "active",
  "paired_at": "2026-07-16T10:00:00Z"
}

Response fields

FieldTypeDescription
idstringPairing ID used for listing, retrieval, and unpairing. Schedule sinks reference this value through channel_pairing_id.
typestringAlways channel_pairing.
channel_idstringChannel ID.
scope_typestringPairing scope: direct for a private-chat user, or room for a group chat.
scope_external_idstringExternal user or group ID for the scope.
scope_display_namestringUser nickname or group name; an empty string if unavailable. For display only, never for authorization.
identity_idstringBound Forward Identity ID.
template_idstringBound Forward Template ID.
statusstringactive on successful pairing.
paired_atstringPairing completion time.

HTTP error codes

HTTPTypeTrigger
400invalid_request_errorParameters are missing, malformed, or include unknown fields; the pairing code is invalid (including already used) or expired; or the Channel is not in pairing mode.
401authentication_errorPAT or SAT is invalid or expired.
403permission_errorThe caller does not have permission to invoke the API.
404not_found_errorPair, Channel, Identity, or Template does not exist or is inaccessible, or the Channel is archived.
409conflict_errorThe binding target conflicts, the Pair has been unpaired, the Identity is disabled, or concurrent activation conflicts. When pairing by ID, the Channel is not enabled or not bound.

Notes

  • Use channel_pairing_id for retries. The same binding succeeds idempotently when the resources are available and the Pair has not been unpaired. Used or expired pairing codes cannot be used to pair again.
  • To change a binding, use Update a channel pairing.
  • Messages sent before pairing succeeds are not replayed automatically. Send them again.

Create a channel

Unpair a channel

List channel pairings

Get a channel pairing

Update a channel pairing

First steps
Define your agent
Configure agent environment
Delegate work to your agent
Agent integrations
Manage agent context
Account
Best Practices
Announcements
API reference