文档中心
即时通讯
服务端 API
会话相关
置顶会话

置顶会话

更新时间：2024-02-18 18:58

描述

调用此接口，可为用户批量置顶或取消置顶至多 20 个会话。如需上调，请联系 ZEGO 技术支持。

客户端将通过 ZIM SDK 的回调接口，接收会话的置顶状态变化。

iOS	Android	macOS	Windows	Web
conversationChanged	onConversationChanged	conversationChanged	onConversationChanged	conversationChanged
小程序	Flutter	React Native	uni-app	Unity3D
conversationChanged	onConversationChanged	conversationChanged	conversationChanged	OnConversationChanged

接口原型

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

请求参数

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

参数	类型	是否必选	描述
FromUserId	String	是	为此 UserID 设置会话的置顶状态。
ConvList	Arrar of Object	是	会话列表，默认长度限制20。
ConvId	String	是	会话 ID。单聊时，conversationID 即是对端用户的 userID。群聊时，conversationID 即是群组的 groupID。
ConvType	Number	是	会话类型： 0：单聊会话。 2：群聊会话。
PinnedType	Number	是	置顶操作： 0：取消置顶。 1：设置置顶。

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

请求示例

请求地址 URL：

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

请求消息体：

{
    "FromUserId": "user0",
    "ConvList": [
        {
            "ConvId": "user1",
            "ConvType": 0
        },
        {
            "ConvId": "user2",
            "ConvType": 0
        }
    ],
    "PinnedType": 1
}

响应参数

参数	类型	描述
Code	Number	返回码。当您发起请求修改多个会话的置顶状态时：只需成功修改 1 个或以上会话的状态，Code 都会返回 0，表示成功。此时请参考 ErrorList 中的具体信息，了解会话修改状态失败详情。如果所有会话的状态都修改失败，Code 会返回相关返回码，具体请参考全局返回码。
Message	String	请求结果的说明信息。
RequestId	String	请求 ID。
ErrorList	Array of Object	失败列表。 Code 为 0： ErrorList 为空，全部会话的置顶状态修改成功。 ErrorList 不为空，表示部分会话的置顶状态修改失败。请参考 SubCode、SubMessage 处理。 Code 不为 0： ErrorList 为空，表示参数错误、接口频率限制、系统错误。 ErrorList 不为空，表示全部会话置顶状态都修改失败。
ConvId	String	置顶状态修改失败的会话 ID。
ConvType	Number	会话类型。
SubCode	Number	置顶状态修改失败的具体错误码。
SubMessage	String	具体错误描述。

响应示例

{
    "Code": 0,
    "Message": "success",
    "RequestId": "343649807833778782",
    "ErrorList": [
        {
            "ConvId": "user1",
            "ConvType": 0,
            "SubCode": 660000002,
            "SubMessage": "input params error"
        }
    ]
}

返回码

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

返回码	说明	处理建议
660000001	业务类通用错误。	请重试，或联系 ZEGO 技术支持。
660000002	输入参数错误。	请检查输入的参数。
660300005	调用接口的频率超出了 AppID 级别限制。	请稍后再试。
660500002	`FromUserId` 未注册。	请先注册 `FromUserId`。
660800001	置顶单聊会话时，操作目标会话 `ConvID` 对应的用户未注册。	请确认该 `ConvId` 对应的用户是否已注册：确认已注册，请联系 ZEGO 技术支持排查。确认未注册，请注册此用户。
660800048	置顶列表长度超过限制（100，不可配置）。	无需处理。