文档中心
即时通讯
服务端 API
会话相关
查询会话列表

查询会话列表

更新时间：2024-04-21 17:04

描述

调用此接口，分页拉取指定用户的全量会话列表，最多返回 1000 个最新会话（单聊与群聊）。

即便用户被踢出会话，本接口返回结果仍包含该会话；但是如果会话解散，则无法通过本接口获取该会话相关信息。

接口原型

请求方法：POST
请求地址：https://zim-api.zego.im/?Action=QueryConversationList
传输协议：HTTPS
调用频率限制：20次/秒。

请求参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表请参考调用方式 - 公共请求参数。

参数	类型	是否必选	描述
FromUserId	String	是	查询此 UserID（已注册）的会话列表。
Limit	Number	否	单次获取会话的数量，默认为 100，取值范围为 (0, 500]。当值 ≤ 0 时，修正为 100。当值 > 500，修正为 500。
Next	Number	否	分页拉取标志，第一次填 0 ，之后填上一次返回的 Next 值。当返回的 Next 为 0 时，代表好友列表获取完毕。例如，FromUserId 有 250 个会话，调用本接口查询时：第一次调用本接口，Limit 填 100，Next 传 0，查询第 1 ～100 个会话；返回结果中的 Next 值为 num1。第二次调用本接口，Limit 填 100，Next 填 num1，查询第 101 ～ 200 个会话；返回结果中 Next 值为 num2。第三次调用本接口，Limit 填 100，Next 填 num2，查询第 201 ～ 250 个会话；查询完毕，返回结果中的 Next 为 0。

FromUserId 仅支持数字，英文字符和 '!'，'#'，'$'，'%'，'&'，'('，')'，'+'，''，':'，';'，'<'，'='，'.'，'>'，'?'，'@'，'['，']'，'^'，'_'，' '，'{'，'}'，'|'，'~'。

请求示例

请求地址 URL：

https://zim-api.zego.im/?Action=QueryConversationList
&<公共请求参数>

请求消息体：

{
    "FromUserId": "u1",
    "Limit": 10,
    "Next": 0
}

响应参数

参数	类型	描述
Code	Number	返回码。
Message	String	请求结果的说明信息。
RequestId	String	请求 ID。
TotalCount	Number	当前的会话总数。
Next	Number	分页拉取标志。非 0：表示还有会话信息未返回，需要将该字段设置到请求参数 Next 中拉取更多会话信息。为 0：表示已经返回完整会话列表。
List	Array of Object	会话列表。按 UpdateTime 升序返回结果。
ConvId	String	会话 ID。单聊会话：会话 ID 为对端用户的 ID。群聊会话：会话 ID 为群组 ID。
ConvType	Number	会话类型。 0 或没有返回此字段：单聊会话。 2：群聊会话。
UpdateTime	Number	会话最后修改时间，毫秒时间戳。

响应示例

{
    "Code": 0,
    "Message": "success",
    "RequestId": "343649807833778782",
    "TotalCount": 500,
    "Next": 1000,
    "List": [
        {
            "ConvId": "conv1",
            "ConvType": 2,
            "UpdateTime": 1708254395000
        },
        {
            "ConvId": "conv2",
            "ConvType": 0,
            "UpdateTime": 1708254395000
        },
        {
            "ConvId": "conv3",
            "UpdateTime": 1708254395000
        },
        ...
    ]
}

返回码

以下仅列出了接口业务逻辑相关的返回码，完整返回码请参考全局返回码。

返回码	说明	处理建议
660000002	输入参数错误。	请检查输入的参数。
660300005	调用接口的频率超出了 AppID 级别限制。	请稍后再试。
660500002	`FromUserId` 未注册。	请检查 `FromUserId` 是否正确。
660800053	查询会话列表失败。	请联系 ZEGO 技术支持。