OpenIM文档

输入至少两个字符来搜索标题和路径。

简中

语言

ENEnglishEnglish docs简中简体中文中文文档
浏览 平台 API
服务端 API

获取排序会话列表

复制

使用 获取排序会话列表 从可信后端调用 OpenIM 会话 REST 接口。按置顶状态和最新消息时间分页获取用户会话列表，并返回未读数和最新消息摘要。 请先在接入准备中配置 API 地址和管理员 Token；接口参数通过请求头和 JSON 请求体传递。

HTTP 请求

POST {API_ADDRESS}/conversation/get_sorted_conversation_list

请求示例

curl --request POST "${API_ADDRESS}/conversation/get_sorted_conversation_list" \
  --header "Content-Type: application/json; charset=utf-8" \
  --header "operationID: ${OPERATION_ID}" \
  --header "token: ${ADMIN_TOKEN}" \
  --data-raw '{
  "userID": "user_001",
  "conversationIDs": [
    "si_user_001_user_002"
  ],
  "pagination": {
    "pageNumber": 1,
    "showNumber": 20
  }
}'
安全提示：管理员 Token 只能保存在可信后端服务中，不能下发到客户端或写入前端代码。客户端登录应使用服务端签发的用户 Token。

参数

此接口通过请求头传入链路追踪信息和鉴权凭证，通过 JSON 请求体传递业务参数。

请求头

Header是否必填类型说明
operationID是string每次请求的唯一链路追踪 ID，建议由后端生成并写入日志。
token是stringAPP 管理员 Token；仅保存在可信后端服务中。
Content-Type: application/json是string请求体为 JSON 时必须设置。

请求体

{
  "userID": "user_001",
  "conversationIDs": [
    "si_user_001_user_002"
  ],
  "pagination": {
    "pageNumber": 1,
    "showNumber": 20
  }
}
参数名是否必填类型说明
userID是string目标用户 ID。
conversationIDs否array指定会话 ID 列表；不传时按分页读取该用户会话。
pagination是object分页参数。
pagination.pageNumber是int页码，从 1 开始。
pagination.showNumber是int每页数量，必须大于 0。

响应

请求被 OpenIM 正常处理时通常返回 200 OK。业务是否成功以响应体中的 errCode 为准；errCode === 0 表示成功，非 0 表示业务错误。

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "conversationTotal": 2,
    "unreadTotal": 3,
    "conversationElems": [
      {
        "conversationID": "si_user_001_user_002",
        "recvMsgOpt": 0,
        "unreadCount": 2,
        "IsPinned": false,
        "msgInfo": {
          "serverMsgID": "server_msg_001",
          "clientMsgID": "client_msg_001",
          "sessionType": 1,
          "sendID": "user_002",
          "recvID": "user_001",
          "senderName": "Jane",
          "faceURL": "https://example.com/avatar-jane.png",
          "groupID": "",
          "groupName": "",
          "groupFaceURL": "",
          "groupType": 0,
          "groupMemberCount": 0,
          "LatestMsgRecvTime": 1719800000000,
          "msgFrom": 100,
          "contentType": 101,
          "content": "{\"content\":\"hello\"}",
          "ex": ""
        }
      }
    ]
  }
}

响应参数

参数名类型说明
errCodeint业务错误码，0 表示成功。
errMsgstring错误简要信息，成功时通常为空。
errDltstring错误详细信息，成功时通常为空。
dataobject接口返回数据。
data.conversationTotalint符合条件的会话总数。
data.unreadTotalint未读消息总数。
data.conversationElemsarray排序后的会话摘要列表，包含会话 ID、收消息选项、未读数、置顶状态和最新消息摘要。

错误

如果请求失败，OpenIM 返回错误对象。更多错误码说明见错误码。

{
  "errCode": 1004,
  "errMsg": "RecordNotFoundError",
  "errDlt": ": [1004]RecordNotFoundError"
}
错误场景可能原因处理方式
鉴权失败token 缺失、过期，或不是可调用管理端接口的管理员 Token。重新获取 APP 管理员 Token，并只在可信后端保存。
链路追踪困难operationID 缺失或在大量请求中重复使用。为每次请求生成独立 operationID，并在服务端日志中保留。
参数校验失败请求体字段类型、必填字段或枚举值不符合接口要求。对照请求体参数表和限制说明检查字段。

权限和限制

  • 只读查询，不改变会话状态。
  • userID 和 pagination 必填。
  • pagination.pageNumber 必须大于等于 1。
  • 所有数组型请求参数建议控制在 1000 个元素以内。

相关页面