ConvPinned

POST

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

By calling this API, you can batch pin or unpin up to 20 conversations for users. If you need to increase this limit, please contact ZEGOCLOUD Technical Support.

The client will receive changes in the pin status of conversations through the following ZIM SDK callback:

iOS	Android	macOS	Windows
conversationChanged	onConversationChanged	conversationChanged	onConversationChanged

Web	Mini Program	Flutter	React Native
conversationChanged	conversationChanged	onConversationChanged	conversationChanged

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

QPS Limit

20 times/s

Request

Query Parameters

Action stringrequired

Possible values: [ConvPinned]

API prototype parameter

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

AppId uint32required

💡Public parameter. Application ID, assigned by ZEGOCLOUD. Get it from the ZEGOCLOUD Admin Console.

SignatureNonce stringrequired

💡Public parameter. A 16-character hexadecimal random string (hex encoding of 8-byte random number). Refer to Signature example for how to generate.

Timestamp int64required

💡Public parameter. Current Unix timestamp, in seconds. Refer to Signature example for how to generate, with a maximum error of 10 minutes.

SignatureVersion stringrequired

Possible values: [2.0]

Default value: 2.0

💡Public parameter. Signature version number.

Signature stringrequired

💡Public parameter. Signature, used to verify the legitimacy of the request. Refer to Signing the requests for how to generate an API request signature.

application/json

Body

required

FromUserId stringrequired

Possible values: <= 32 characters

Set the pin status of conversations for this UserID (who has logged in to the ZIM service by calling the login method on the client, or has completed registration by calling the server-side API).

Note

FromUserId only supports numbers, English characters, and "'!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', ' ', '{', '}', '|', '~'".

ConvList object[]required

Possible values: <= 20

Conversation list, default length limit is 20.

Array[

ConvId stringrequired

Possible values: <= 32 characters

Conversation ID.

For one-on-one chats, conversationID is the userID of the peer user (who has logged in to the ZIM service by calling the login method on the client, or has completed registration by calling the server-side API).
For group chats, conversationID is the groupID of the group.

ConvType numberrequired

Possible values: [0, 2]

Conversation type:

0: One-on-one conversation.
2: Group conversation.

]

PinnedType numberrequired

Possible values: [0, 1]

Pin operation:

0: Unpin.
1: Pin.

Responses

application/json

Schema
Example (from schema)

Schema

Code number

Return code.

The following only lists the Code and SubCode related to the API business logic. For the complete return codes, please refer to Return codes.

Note

When you request to modify the pin status of multiple conversations:

As long as the status of 1 or more conversations is successfully modified, Code will return 0, indicating success. In this case, please refer to the specific information in ErrorList to understand the details of failed conversation status modifications.

If the status of all conversations fails to be modified, Code will return the relevant return code. For details, please refer to Return codes.

Code / SubCode	Description	Suggested Solution
660000001	General business error.	Please retry or contact ZEGOCLOUD Technical Support.
660000002	Input parameter error.	Please check the input parameters.
660300005	The API call frequency exceeds the AppID-level limit.	Please try again later.
660500002	FromUserId is not registered.	Please register FromUserId first.
660800001	When pinning a one-on-one conversation, the user corresponding to the target conversation ConvID is not registered.	Please confirm if the user corresponding to this ConvId is registered: If confirmed registered, please contact ZEGOCLOUD Technical Support for troubleshooting. If confirmed not registered, please register this user.
660800048	Pin list length exceeds the limit (100, not configurable).	No action needed.

Message string

Description of the request result.

RequestId string

Request ID.

ErrorList object[]

Failure list.

When Code is 0:
If ErrorList is empty, the pin status of all conversations has been successfully modified.
If ErrorList is not empty, it means the pin status modification of some conversations failed. Please refer to SubCode and SubMessage for handling.
When Code is not 0:
If ErrorList is empty, it indicates parameter error, API frequency limit, or system error.
If ErrorList is not empty, it means the pin status modification of all conversations failed.

Array[

ConvId string

Conversation ID for which the pin status modification failed.

ConvType number

Conversation type.

SubCode number

Specific error code for the failed pin status modification. For the complete return codes, please refer to the Code description or Return codes.

SubMessage string

Specific error description.

]

{
  "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"
    }
  ]
}