会话
列出会话
实时列出账号下的会话。limit 范围 1..100，默认 20；type 是逗号分隔的 user / group / channel 精确值，不会 trim。WhatsApp 未传 label_id 时只返回“特别关注”会话。cursor 不透明，失效或伪造游标可能被拒绝，也可能按渠道重新从头分页。
https://api.unifyport.ai/v1/accounts/{account_id}/conversations调用前准备
在服务端使用资源所属工作区的 X-Api-Key。运行示例前替换所有占位符。
参数从哪里取得
- account_id
- 从创建或查询账号的响应取得 data.id。账号标识属于 X-Api-Key 对应的工作区。 获取账号
请求参数
请求头
X-Api-Key工作区 API Key，工作区由该请求头解析得到。
路径参数
account_id用于该 conversations 路由的标识符。
查询参数
type逗号分隔的 user、group、channel 精确值；不会 trim 或规范化。
cursor上一响应的 next_cursor。省略或留空从第一页开始；失效或伪造游标在不同渠道上的处理不统一。
limit单页数量范围 1..100；各列表接口的默认值见对应页面说明。
minimum: 1 · maximum: 100
label_id渠道标签精确标识；WhatsApp 省略时返回“特别关注”会话。
请求体
该接口无需 JSON 请求体。
如何理解结果
按文档解释响应字段和 HTTP 状态。204 成功响应没有响应体，排查时使用 X-Request-Id。下一步操作见相关链接。
响应 200 OK
{
"request_id": "<REQUEST_ID>",
"data": {
"items": [
{
"conversation_id": "peer_example",
"type": "user",
"title": "Display name",
"avatar_url": "",
"unread_count": 3,
"last_message_at": "2026-05-13T10:00:00Z"
}
],
"next_cursor": "",
"has_more": false
}
}
响应体
conversation_id会话标识，发送消息或调用会话路由时作为目标使用。
type会话类型：user、group 或 channel。
enum: user, group, channel
title会话的显示标题。
username渠道提供时返回的会话用户名。
avatar_url头像 URL，未设置时为空字符串。
description群组或频道描述，存在时返回。
last_message_at最近一条消息的 RFC3339 时间戳。
format: date-time
last_message_text最近一条消息的文本摘要，存在时返回。
unread_count会话中的未读消息数。
format: int64
members_count成员数量；群组会话时返回。
format: int64
subscribers_count频道类会话的订阅者数量，存在时返回。
format: int64
is_pinned该会话是否被当前账号置顶。
is_muted该会话是否被当前账号静音。
created_at渠道提供时返回的会话创建时间。
format: date-time
extra标准字段未覆盖的渠道专属内容。
next_cursor指向下一页的不透明游标，回传作为 cursor 使用；空字符串表示没有更多页。
has_more当本页之外还有更多结果时为 true。
响应
200200 OK
请求成功，响应体示例如上。
400请求错误
请求体、路径或参数不合法。
401未授权
X-Api-Key 请求头缺失或无效。
409冲突
当前操作与已有的渠道账号或资源冲突。
500服务端错误
服务端遇到了未预期的错误。
501渠道未实现
所选渠道尚未实现该操作。
502上游网关错误
渠道适配器或上游渠道未能完成该操作。
失败后怎么处理
检查 HTTP 状态和 error.code/numeric_code，保存 request_id 用于排查。按原因修正参数、继续授权或检查运行态。重试发送及其他写操作前先确认上一次结果，避免重复操作。 错误码参考
- invalid_request · 10000 · 400
- 检查必填字段、格式和渠道条件，修正请求后再调用。
- invalid_api_key · 11001 · 401
- 检查 X-Api-Key 是否正确、工作区是否有效。