Configuring Unread Message Counts

Last updated: 2020-03-12 15:06:29


Feature Description

  • The app admin uses this API to set the unread message count of a group member. When this API is called, no callback is triggered and no notification is sent.
  • When the app needs to be migrated from another IM system to Tencent Cloud IM, this API is used to set the unread message count of group members.

API Calling Description

Applicable group types

Group Type Support This RESTful API
Private Yes
Public Yes
ChatRoom No (see the following note)
AVChatRoom No (see the following note)
BChatRoom No (see the following note)

IM provides the preceding five built-in group types. For details, see the Group System.

ChatRoom, AVChatRoom, and BChatRoom clients do not support unread message counts. Therefore, setting the unread message count is invalid for these types of groups, but no error message will be returned.

Request URL example

Request parameters

The following table lists only the parameters to be modified when this API is called. For details on other parameters, see RESTful API Overview.

Parameter Description
v4/group_open_http_svc/set_unread_msg_num Request API
sdkappid SDKAppID assigned by the IM console when an app is created
identifier The value must be the app admin account. For details, see App Admins.
usersig Signature generated by the app admin account. For details, see Generating UserSig.
random A random 32-bit unsigned integer ranging from 0 to 4294967295

Maximum calling frequency

The maximum calling frequency is 200 times per second.

Request packet example

Sets the unread message count of a specified group member.
If the unread message count specified by this API is greater than the current number of messages of the group, the unread message count is set to the current number of messages of the group.

    "GroupId": "@TGS#2CLUZEAEJ", // Target group (required)
    "Member_Account": "bob", // Target group member (required)
    "UnreadMsgNum":5          // Unread message count of this member

Request packet fields

Field Type Attribute Description
GroupId String Required ID of the target group
Member_Account String Required Target group member
UnreadMsgNum Integer Required Unread message count of the member

Response packet example

    "Action1Status": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0

Response packet fields

Field Type Description
ActionStatus String Request processing result. OK: succeeded. FAIL: failed.
ErrorInfo String Error information
ErrorCode Integer Error code. 0: succeeded. Others: failed.

Error Codes

Unless a network error (such as error 502) occurs, the HTTP return code for this API is always 200. ErrorCode and ErrorInfo in the response packet represent the actual error code and error information, respectively.
For common error codes (60000 to 79999), see Error Codes.
The following table describes the error codes specific to this API.

Error Code Description
10002 An internal server error occurred. To correct it, try again.
10003 The request command word is invalid.
10004 A parameter is invalid. To correct it, check whether request parameters are correct based on the error description.
10007 Operation permissions are insufficient. For example, a common member in a public group attempts to remove a member from the group, but only the app admin has the permission to do so.
10010 The group does not exist or has been dismissed.
10015 The group ID is invalid. To correct it, check whether the group ID is correct.

API Commissioning Tool

Use the online commissioning tool for RESTful APIs to commission this API.


Sending system notifications in a group (v4/group_open_http_svc/send_group_system_notification)