Documentation
In-app Chat
Server APIs
Conversation related
Pin conversations to the top

Pin or unpin conversations to or from the top

Last updated：2024-03-22 15:50

Overview

You can call this operation to batch pin or unpin up to 20 conversations to or from the top for a user. If you need a higher limit, contact ZEGOCLOUD technical support.

The client receives the change for conversations being pinned or unpinned in the following ZIM SDK callbacks.

iOS	Android	macOS	Windows	Web
conversationChanged	onConversationChanged	conversationChanged	onConversationChanged	conversationChanged
Flutter	React Native	Unity3D
onConversationChanged	conversationChanged	OnConversationChanged

Operation prototype

Request method: POST
Request URL: https://zim-api.zego.im/?Action=ConvPinned
Protocol: HTTPS
QPS limit: 20 calls per second

Request parameters

The following table describes only the operation-specific request parameters and some common request parameters. For the complete list of common request parameters, see the Public request parameters section of the Accessing Server APIs topic.

Parameter	Type	Required	Description
FromUserId	String	Yes	The user ID for which conversations are to be pinned or unpinned.
ConvList	Arrar of Object	Yes	The list of conversations. By default, up to 20 conversations can be included.
ConvId	String	Yes	The conversation ID. In a one-to-one chat, set `conversationID` to the ID of the other user. In a group chat, set `conversationID` to the ID of the group.
ConvType	Number	Yes	The conversation type. Valid values: `0`: one-to-one chat. `2`: group chat.
PinnedType	Number	Yes	Specifies whether to pin conversations to the top. Valid values: `0`: no. `1`: yes.

The FromUserId parameter can contain only digits, letters, and the following characters: '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', ' ', '{', '}', '|', '~'.

Sample request

Request URL:

https://zim-api.zego.im/?Action=ConvPinned
&<Common request parameters>

Request body:

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

Response parameters

Parameter	Type	Description
Code	Number	The return code. When you request to pin or unpin multiple conversations, take note of the following items: If one or more conversations are successfully pinned or unpinned, `0` is returned, indicating a success. For more information, see `ErrorList`. If all conversations fail to be pinned or unpinned, a corresponding code is returned. For more information, see Return codes.
Message	String	The description of the request result.
RequestId	String	The request ID.
ErrorList	Array of Object	The list of failed results. If `Code` is `0`: If `ErrorList` is empty, all conversations are successfully pinned or unpinned. If `ErrorList` is not empty, some conversations fail to be pinned or unpinned. In this case, see `SubCode` and `SubMessage`. If `Code` is not `0`: If `ErrorList` is empty, one or more parameters are invalid, the QPS limit is exceeded, or a system error occurs. If `ErrorList` is not empty, all conversations fail to be pinned or unpinned.
ConvId	String	The ID of the conversation that fails to be pinned or unpinned.
ConvType	Number	The conversation type.
SubCode	Number	The code returned when the request fails.
SubMessage	String	The error message.

Sample response

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

Return codes

The following table describes only the return codes related to the business logic of the operation. For the complete list of return codes, see Return codes.

Return Code	Description	Solution
660000001	A common service error occurred.	Try again, or contact ZEGOCLOUD technical support.
660000002	Invalid parameter.	Check the input parameter.
660300005	The QPS limit specified in `AppID` is exceeded.	Try again later.
660500002	`FromUserId` is not registered.	Register `FromUserId`.
660800001	If a one-to-one chat is to be pinned or unpinned, this indicates that the user in the conversation (`ConvID`) is not registered.	Check whether the user in the conversation (`ConvID`) is registered. - If so, contact ZEGOCLOUD technical support. - If not, register the user.
660800048	Too many conversations are included in the list. The maximum value is `100` and cannot be changed.	No handling is required.

ZEGO UIKits

Cloud Communications Products

Low-Code Products

AIGC

Supporting Services