SetConvMark

POST

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

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

The client will receive changes in conversation marks 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: [SetConvMark]

API prototype parameter

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

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

Operator user ID (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 "'!', '#', '$', '%', '&', '(', ')', '+', '', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', ' ', '{', '}', '|', '~'".

ConvMarkInfoList object[]required

Possible values: <= 100

Conversation mark objects, maximum 100 per request. An error will be reported if it exceeds 100 or is 0.

Array[

UserId stringrequired

Set or cancel conversation marks for this UserID.

Note

When the target conversation is a group chat, this user must already be in the group chat.

Note

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

SetMarkC2c object

At least one of SetMarkC2c and SetMarkGroup must be selected.
One-on-one conversation list (JSON Object). The key is the conversation ID, and the value is a JSON Object containing only the key MarkContent. The list can contain up to 100 conversations.

property name* object

MarkContent numberrequired

Possible values: >= 1 and <= 30

Conversation mark. An integer value in the range [1, 30].

SetMarkGroup object

At least one of SetMarkC2c and SetMarkGroup must be selected.
Group conversation list (JSON Object). The key is the conversation ID, and the value is a JSON Object containing only the key MarkContent. The list can contain up to 100 conversations (group conversations must already exist and not be deleted).

property name* object

MarkContent numberrequired

Possible values: >= 1 and <= 30

Conversation mark. An integer value in the range [1, 30].

Action booleanrequired

Mark operation:

true: Set mark.
false: Cancel mark.

]

Responses

application/json

Schema
Example (from schema)

Schema

Code number

Return code.

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

Note

When you request to set or cancel marks for multiple conversations:

As long as the operation is successfully completed for at least one conversation, Code will return 0, indicating success. In this case, please refer to the specific information in FailList to understand the details of failed operations.

If the operations for all conversations fail, Code will return the relevant return code. For details, please refer to Return codes.

Return code	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.
660800001	Error querying user information.	Please contact ZEGOCLOUD Technical Support.
660800054	Mark operations for all conversations failed.	Please contact ZEGOCLOUD Technical Support.

Message string

Description of the request result.

RequestId string

Request ID.

FailList object[]

List of users for whom conversation mark operations failed.

When Code is 0:
If FailList is empty, conversation mark operations for all users succeeded.
If FailList is not empty, it means conversation mark operations for some users failed. Please refer to SubCode and SubMessage in FailList for handling.
When Code is not 0:
If FailList is empty, it indicates parameter error, API frequency limit, or system error.
If FailList is not empty, it means conversation mark operations for all users failed.

Array[

SubCode number

Used to identify the result of executing conversation mark operations for a user.

SubMessage string

Describes the result of executing conversation mark operations for a user.

UserId string

ID of the target user for the conversation mark operation.

FailList object[]

List of target conversations for which mark operations failed.

When SubCode is 0:
If FailList is empty, operations for all target conversations of the target user succeeded.
If FailList is not empty, it means operations for some target conversations of the target user failed. Please refer to Code and Message in FailList for handling.
When SubCode is not 0:
If FailList is empty, it indicates parameter error, API frequency limit, or system error.
If FailList is not empty, it means operations for all target conversations of the target user failed.

Array[

Code number

Return code for failed operation.

Message string

Description of failed operation.

ConvId string

Conversation ID.

One-on-one conversation: Conversation ID is the user ID.
Group conversation: Conversation ID is the group ID.

ConvType number

Possible values: [0, 2]

Conversation type.

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

]

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

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

SetConvMark

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

Request

Query Parameters

Body

Responses​

Responses