API 参考

会话

获取会话详情

实时返回一条会话的详情。conversation_id 通过 query 参数传入（值即 List conversations 返回的 id）。响应固定包含 conversation_id / type / title / avatar_url（缺失时为空字符串），并按类型补充字段，例如群组的 members_count；找不到会话时返回 404。

GEThttps://api.unifyport.ai/v1/accounts/{account_id}/conversations/info

调用前准备

在服务端使用资源所属工作区的 X-Api-Key。运行示例前替换所有占位符。

参数从哪里取得
account_id
从创建或查询账号的响应取得 data.id。账号标识属于 X-Api-Key 对应的工作区。 获取账号
conversation_id
要查询的会话——即 List conversations 返回的 conversation_id 值。

请求参数

请求头

X-Api-Key
string必填

工作区 API Key，工作区由该请求头解析得到。

路径参数

account_id
string必填

用于该 conversations 路由的标识符。

查询参数

conversation_id
string必填

要查询的会话——即 List conversations 返回的 conversation_id 值。

type
string

用于消歧查询的会话类型（user、group 或 channel）。

enum: user, group, channel

请求体

该接口无需 JSON 请求体。

如何理解结果

按文档解释响应字段和 HTTP 状态。204 成功响应没有响应体，排查时使用 X-Request-Id。下一步操作见相关链接。

响应 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "conversation_id": "peer_example",
    "type": "group",
    "title": "Group title",
    "avatar_url": "",
    "description": "...",
    "unread_count": 0,
    "members_count": 42
  }
}

响应体

conversation_id
string

会话标识，发送消息或调用会话路由时作为目标使用。

type
string

标准会话类型：user、group 或 channel。WhatsApp 社群公告群继续使用 group。

enum: user, group, channel

title
string

会话的显示标题。

username
string

渠道提供时返回的会话用户名。

avatar_url
string

头像 URL，未设置时为空字符串。

description
string

群组或频道描述，存在时返回。

last_message_at
string

最近一条消息的 RFC3339 时间戳。

format: date-time

last_message_text
string

最近一条消息的文本摘要，存在时返回。

unread_count
integer

会话中的未读消息数。

format: int64

members_count
integer

成员数量；群组会话时返回。

format: int64

subscribers_count
integer

频道类会话的订阅者数量，存在时返回。

format: int64

is_pinned
boolean

该会话是否被当前账号置顶。

is_muted
boolean

该会话是否被当前账号静音。

created_at
string

渠道提供时返回的会话创建时间。

format: date-time

extra
object

渠道扩展字段；WhatsApp 群会话可包含公告群分类，会话列表不保证提供该分类。

is_announcement_group
boolean

仅 WhatsApp 群提供。true 表示已确认是社群公告群，false 表示本次资料已确认不符合公告群条件；缺失表示未知，不返回 null。此分类不表示当前账号具备发送消息的权限。

响应

200

200 OK

请求成功，响应体示例如上。

400

请求错误

请求体、路径或参数不合法。

401

未授权

X-Api-Key 请求头缺失或无效。

404

未找到

未找到请求的渠道资源。

409

冲突

当前操作与已有的渠道账号或资源冲突。

500

服务端错误

服务端遇到了未预期的错误。

501

渠道未实现

所选渠道尚未实现该操作。

502

上游网关错误

渠道适配器或上游渠道未能完成该操作。

失败后怎么处理

检查 HTTP 状态和 error.code/numeric_code，保存 request_id 用于排查。按原因修正参数、继续授权或检查运行态。重试发送及其他写操作前先确认上一次结果，避免重复操作。 错误码参考

invalid_request · 10000 · 400
检查必填字段、格式和渠道条件，修正请求后再调用。
invalid_api_key · 11001 · 401
检查 X-Api-Key 是否正确、工作区是否有效。