Documentation
In-app Chat
Server APIs
Conversation related
Set Conversation Marks

Set Conversation Marks

Last updated：2024-08-09 11:54

Overview

By calling this API, you can set or cancel marks on multiple conversations for multiple users. Each conversations can have up to 20 marks.

The client will receive mark changes of conversations through the following callback interface of the ZIM SDK:

iOS	Android	macOS	Windows	Web
conversationChanged	onConversationChanged	conversationChanged	onConversationChanged	conversationChanged
小程序	Flutter	React Native
conversationChanged	onConversationChanged	conversationChanged

Request method and endpoint

Request method: POST
Request endpoint: https://zim-api.zego.im/?Action=SetConvMark
Protocol: HTTPS
Rate limit: 20 times/second

Request parameters

The following list only shows the request parameters for this interface and some public parameters. For a complete list of public parameters, please refer to Accessing Server APIs - Public parameters.

Parameter	Type	Required	Description
FromUserId	String	Yes	User ID of the operator (registered).
ConvMarkInfoList	Array of StConvMarkInfoList	Yes	Objects for conversation marking, up to 100 each time. An error will be reported if it exceeds 100 or is 0.

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

StConvMarkInfoList Description

Parameter	Type	Required	Description
UserId	String	Yes	Sets or cancels the mark for this UserID's conversations.
SetMarkC2c	Object of ConvMarkInfo	At least one is required	One-to-one conversation list. The key is the conversation ID, and the value is the ConvMarkInfo structure. The list can contain up to 100 conversations.
SetMarkGroup	Object of ConvMarkInfo	At least one is required	Group conversation list. The key is the conversation ID, and the value is the ConvMarkInfo structure. The list can contain up to 100 conversations.
Action	Bool	Yes	Mark operation: true: set marks. false: cancel marks.

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

ConvMarkInfo Description

Parameter	Type	Required	Description
MarkContent	Number	Yes	Mark. An integer ranging from 1 to 20.

Sample request

Request URL:

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

Request body:

{
    "FromUserId": "user_test",
    "ConvMarkInfoList": [
        {
            "UserId": "userA",
            "SetMarkC2c": {
                "conv_c2c_1": {
                    "MarkContent": 2
                },
                "conv_c2c_2": {
                    "MarkContent": 2
                }
            },
            "SetMarkGroup": {
                "conv_group_1": {
                    "MarkContent": 2
                },
                "conv_group_2": {
                    "MarkContent": 2
                }
            },
            "Action": true
        },
        {
            "UserId": "userB",
            "SetMarkC2c": {
                "conv_c2c_1": {
                    "MarkContent": 2
                },
                "conv_c2c_2": {
                    "MarkContent": 2
                }
            },
            "SetMarkGroup": {
                "conv_group_1": {
                    "MarkContent": 2
                },
                "conv_group_2": {
                    "MarkContent": 2
                }
            },
            "Action": true
        }
    ]
}

Response parameters

Parameter	Type	Description
Code	Number	Return code. When you initiate a request to set or cancel marks for multiple conversations: If you successfully complete the operation for at least 1 conversation, Code will return 0, indicating success. Please refer to the specific information in FailList to understand the details of the failed operations. If all operations for the conversations fail, Code will return the corresponding return code. Please refer to the Return Codes for details.
Message	String	Description of the request result.
RequestId	String	Request ID.
FailList	Array of UserFailList	List of users for whom the conversation marker failed. Code is 0: FailList is empty, indicating that the conversation marker operation was successful for all users. FailList is not empty, indicating that the conversation marker operation failed for some users. Please refer to SubCode and SubMessage in FailList for details. Code is not 0: FailList is empty, indicating parameter error, interface rate limit, or system error. FailList is not empty, indicating that the conversation marker operation failed for all users.

UserFailList Description

Parameter	Type	Description
SubCode	Number	Used to identify the result of a conversation marking operation performed for a user.
SubMessage	String	Describes the result of a conversation marking operation performed for a user.
UserId	String	ID of the target user for whom the conversation marking operation is performed.
FailList	Array of ConvMarkFailList	Failed target conversation list of marking operations for the target user. If SubCode is 0: FailList is empty, indicating that all conversation marking operations for the target user were successfully operated on. FailList is not empty, indicating that some conversation marking operations for the target user failed. Please refer to the Code and Message in FailList for handling. If SubCode is not 0: FailList is empty, indicating parameter error, interface rate limit, or system error. FailList is not empty, indicating that all conversation marking operations for the target user failed.

ConvMarkFailList Description

Parameter	Type	Description
Code	Number	Return code.
Message	String	Description of the failed operation.
ConvId	String	Conversation ID.
ConvType	Number	Type of conversation. 0: One-on-one conversation. 2: Group conversation.

Sample response

{
    "Code": 0,
    "Message": "success",
    "RequestId": "343649807833778782",
    "FailList": [
        {
            "SubCode": 0,
            "SubMessage": "succ",
            "UserId": "UserA",
            "FailList": [
                {
                    "Code": 1,
                    "Message": "mark content is invalide",
                    "ConvId": "conv_id_1",
                    "ConvType": 0
                },
                {
                    "Code": 1,
                    "Message": "mark content is invalide",
                    "ConvId": "conv_id_2",
                    "ConvType": 0
                }
            ]
        },
        {
            "SubCode": 1,
            "SubMessage": "user not exist",
            "UserId": "UserB"
        }
    ]
}

Return codes

The following list only shows the return codes related to the business logic of the interface. For a complete list of return codes, please refer to Return codes.

Return Code	Description	Solution
660000001	Business related general error.	Please try again or contact ZEGOCLOUD Technical Support.
660000002	The parameter entered is missing or invalid.	Please check the parameters.
660300005	The frequency of calling the interface exceeds the limit at the AppID level.	Please try again later.
660800001	Error querying user information.	Please contact ZEGO technical support.
660800054	Marking operations for all conversations have failed.	Please contact ZEGO technical support.