ConvPinned

POST

https://zim-api.zego.im/

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

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

iOS	Android	macOS	Windows
conversationChanged	onConversationChanged	conversationChanged	onConversationChanged

Web	小程序	Flutter	React Native
conversationChanged	conversationChanged	onConversationChanged	conversationChanged

Unity3D	uni-app \| uni-app x	HarmonyOS
OnConversationChanged	conversationChanged	conversationChanged

说明

调用频率限制：20 次/秒。

Request

Query Parameters

Action string必填

可选值: [ConvPinned]

接口原型参数

https://zim-api.zego.im/?Action=ConvPinned

AppId uint32必填

💡公共参数。应用 Id，由 ZEGO 分配的用户唯一凭证。可从 ZEGO 控制台获取。

SignatureNonce string必填

💡公共参数。16 位 16 进制随机字符串（8 字节随机数的 hex 编码）。生成算法可参考签名示例。

Timestamp int64必填

💡公共参数。当前 Unix 时间戳，单位为秒。生成算法可参考签名示例，最多允许 10 分钟的误差。

SignatureVersion string必填

可选值: [2.0]

默认值: 2.0

💡公共参数。签名版本号。

Signature string必填

💡公共参数。签名，用于验证请求的合法性。请参考签名机制生成。

application/json

Body

required

FromUserId string必填

可选值: <= 32 characters

为此 UserID（已在客户端调用 login 方法登录 ZIM 服务，或已调用服务端 API 完成注册）设置会话的置顶状态。

说明

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

ConvList object[]required

Possible values: <= 20

会话列表，默认长度限制20。

Array[

ConvId string必填

可选值: <= 32 characters

会话 ID。

单聊时，conversationID 即是对端用户的 userID（已在客户端调用 login 方法登录 ZIM 服务，或已调用服务端 API 完成注册）。
群聊时，conversationID 即是群组的 groupID。

ConvType number必填

可选值: [0, 2]

会话类型：

0：单聊会话。
2：群聊会话。

]

PinnedType number必填

可选值: [0, 1]

置顶操作：

0：取消置顶。
1：设置置顶。

Responses

application/json

数据结构
按数据结构生成的示例

Schema

Code number

返回码。

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

说明

当您发起请求修改多个会话的置顶状态时：

只需成功修改 1 个或以上会话的状态，Code 都会返回 0，表示成功。此时请参考 ErrorList 中的具体信息，了解会话修改状态失败详情。

如果所有会话的状态都修改失败，Code 会返回相关返回码，具体请参考全局返回码。

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

Message string

请求结果的说明信息。

RequestId string

请求 ID。

ErrorList object[]

失败列表。

Code 为 0：
ErrorList 为空，全部会话的置顶状态修改成功。
ErrorList 不为空，表示部分会话的置顶状态修改失败。请参考 SubCode、SubMessage 处理。
Code 不为 0：
ErrorList 为空，表示参数错误、接口频率限制、系统错误。
ErrorList 不为空，表示全部会话置顶状态都修改失败。

Array[

ConvId string

置顶状态修改失败的会话 ID。

ConvType number

会话类型。

SubCode number

置顶状态修改失败的具体错误码，完整返回码请参考 Code 说明或者全局返回码。

SubMessage string

具体错误描述。

]

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

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