Skip to main content
Channels

列出 Channel 配对

查询调用方可访问的 Channel 配对记录，支持筛选和游标分页。

Channel 配对目前为 Beta 功能，接口定义、响应结构和行为可能调整，请关注文档更新。
GET /api/v1/forward/channel_pairings 使用 Authorization: Bearer <PAT 或 SAT>，仅返回调用方可访问的 Channel 配对记录。默认包含未绑定 pairing 和已绑定 active，不返回已解绑 unbound。

查询参数

参数说明
channel_id可选，指定可访问的 Channel；不传则覆盖全部可访问的 Channel。
status可选，pairing 或 active。配对码过期后 Pair 仍为 pairing。
target_type可选，user（私聊）或 group（群聊）。
target_external_id可选，精确匹配外部用户或群 ID；建议结合 Channel 和目标类型使用。
identity_id / template_id可选，仅筛选已绑定记录，不校验 Identity / Template 是否存在；与 status=pairing 同传时返回空列表。
limit每页条数，默认 20，取值为 1–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。列表不返回配对码、工号或花名，也不生成或刷新配对码。 identity_id / template_id 无匹配绑定时返回 HTTP 200 OK 和空列表，不返回 404： 
{"data":[],"first_id":null,"last_id":null,"has_more":false}
scope_display_name 为用户昵称或群名，可为空，仅供展示。

HTTP 错误码

HTTPType触发条件
400invalid_request_error筛选值非法、limit 超出 1–100、同时传入两个游标，或参数含控制字符。
401authentication_errorPAT 或 SAT 无效或已过期。
403permission_error无调用权限。
404not_found_error指定的 channel_id 不存在或不可访问。

相关接口

获取配对

更新配对