Skip to main content
Channels

List channel pairings

Query accessible Channel pairing records with filters and cursor pagination.

Channel pairing is currently in Beta. API definitions, response structures, and behavior may change. Check the documentation for updates.
GET /api/v1/forward/channel_pairings Use Authorization: Bearer <PAT or SAT>. Only Channel pairing records accessible to the caller are returned. By default, results include pending (pairing) and bound (active) records, but exclude unpaired (unbound) records.

Query parameters

ParameterDescription
channel_idOptional. If omitted, query all Channels accessible to the caller.
statusOptional: pairing or active. A Pair remains in pairing after its pairing code expires.
target_typeOptional: user (private chat) or group (group chat).
target_external_idOptional. Exact match for an external user or group ID. Recommended together with Channel and target type filters.
identity_id / template_idOptional. Filter by the bound execution context; pending records do not match.
limitItems per page. Default: 20. Maximum: 100.
after_id / before_idOptional. Use a returned Pairing id as the cursor. These parameters cannot be used together.

Example

GET /api/v1/forward/channel_pairings?channel_id=channel_019eabc123&status=pairing&target_type=group

{
  "data": [
    {
      "id": "pair_019eabc123",
      "type": "channel_pairing",
      "channel_id": "channel_019eabc123",
      "scope_type": "room",
      "scope_external_id": "external_group_id",
      "scope_display_name": "Project discussion group",
      "status": "pairing",
      "identity_id": "",
      "template_id": "",
      "paired_at": "",
      "created_at": "2026-09-09T08:00:00Z",
      "updated_at": "2026-09-09T08:00:00Z"
    }
  ],
  "first_id": "pair_019eabc123",
  "last_id": "pair_019eabc123",
  "has_more": false
}
scope_type is direct (private chat) or room (group chat). scope_external_id is the corresponding external user or group ID. Bound records return their actual identity_id, template_id, and paired_at. The list does not return pairing codes, employee numbers, or employee aliases, and does not generate or refresh pairing codes. Invalid filter or pagination parameters return 400. A specified resource that is inaccessible or does not exist returns 404. scope_display_name is the user's nickname or group name, or an empty string if unavailable. It is updated by subsequent messages and is for display only. Use the external ID for authorization.

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
List channel pairings - Qoder