查询 Channel 配对

Channel 配对目前为 Beta 功能，接口定义、响应结构和行为可能调整，请关注文档更新。

GET /api/v1/forward/channel_pairings 使用 Authorization: Bearer <PAT 或 SAT>，仅返回调用方可访问的 Channel 配对记录。默认包含未绑定 pairing 和已绑定 active，不返回已解绑 unbound。

查询参数

参数	说明
`channel_id`	可选；不传则查询调用方可访问的全部 Channel。
`status`	可选，`pairing` 或 `active`。配对码过期后 Pair 仍为 `pairing`。
`target_type`	可选，`user`（私聊）或 `group`（群聊）。
`target_external_id`	可选，精确匹配外部用户或群 ID；建议结合 Channel 和目标类型使用。
`identity_id` / `template_id`	可选，筛选已绑定的执行上下文；未绑定记录不匹配。
`limit`	每页条数，默认 20，最大 100。
`after_id` / `before_id`	可选，使用返回的 Pairing `id` 作为游标，不能同时传。

示例

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": "项目讨论群",
      "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 为 direct（私聊）或 room（群聊），scope_external_id 为对应的外部用户或群 ID。已绑定记录返回实际 identity_id、template_id 和 paired_at。列表不返回配对码、工号或花名，也不生成或刷新配对码。非法筛选或分页参数返回 400；不可访问或不存在的指定资源返回 404。 scope_display_name 为用户昵称或群名，未获取到时为空字符串；随后续消息更新，仅供展示，授权请使用外部 ID。

查询 Channel 配对

查询参数

示例

相关接口

获取配对

更新配对

​查询参数

​示例

​相关接口

获取配对

更新配对

查询参数

示例

相关接口