Send messages to tagged members in chat rooms or receive tagged messages only by using the tag feature. This document introduces the tag feature in chat rooms by calling the corresponding APIs.

• Chat room tags are configured when an SDK instance logs in. For a detailed introduction to the chat room tag feature, see Chat room tag.
• In addition to the relevant APIs described in this document, you can set the notifyTargetTags parameter to messages that are delivered to specified users. Messages without notifyTargetTags are sent to all users in the chat room. For more information, see Send messages。

Mute participants usting tags

You can mute users with a specific tag during a specified period of time.

URL

httpPOST https://api.netease.im/nimserver/chatroom/tagTemporaryMute.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

Request parameters

• For information about how to set the header in a POST request, see API Call methods.

• The settings of the body in a POST request:

Parameter	Type	Required	Description
roomid	Long	Yes	Chat room ID.
operator	String	is	The account of an operator, The operator must be the creator or administrator
targetTag	String	Yes	Target tag
needNotify	Boolean	No	Whether a notification is sent when a user is muted. The default value is true.
notifyExt	String	No	Extension field for notifications
muteDuration	int	Yes	The duration for muting in seconds, up to 30 days, if the value is set to 0, a user is unmuted.< /td>
notifyTargetTags	String	No	The target tag expression for mute notifications, if unspecified, the notification will be sent to users with `targetTag`.< /td>

Example

cURL request example

curlcurl -X POST  -H 'appkey: fe416640c8e8a72734219e1847ad2547'  -H 'cache-control: no-cache'  -H 'checksum: 18f5435a7bf287af9150ad608797f75265495034'  -H 'content-type: application/x-www-form-urlencoded'   -H 'curtime: 1508481877'   -H 'nonce: 12345' -d 'targetTag=abc&roomid=3001&operator=xxx&muteDuration=123' "https://api.netease.im/nimserver/chatroom/tagTemporaryMute.action"

Example success response

json"Content-Type": "application/json; charset=utf-8"
{
    "code": 200,
    "desc": {
        "muteDuration": 100 //The muting duration. If a user is unmuted, the remaining mute duration of the last mute will be returned
    }
} 

Status code

The status code returned in the response body. For more information, see Status codes.

Query the number of online users with a specific tag

You can query the number of online users with a specific tag by calling this API.

If a user logs in on multiple devices, the login of this user is counted as 1.

URL

httpPOST https://api.netease.im/nimserver/chatroom/tagMembersCount.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

Request parameters

• For information about how to set the header in a POST request, see API Call methods.

• The settings of the body in a POST request:

Parameter	Type	Required	Description
roomid	Long	Yes	Chat room ID.
tag	string	Yes	Tag

Example

cURL request example

curlcurl -X POST  -H 'appkey: fe416640c8e8a72734219e1847ad2547'  -H 'cache-control: no-cache'  -H 'checksum: 18f5435a7bf287af9150ad608797f75265495034'  -H 'content-type: application/x-www-form-urlencoded'   -H 'curtime: 1508481877'   -H 'nonce: 12345' -d 'tag=abc&roomid=3001' "https://api.netease.im/nimserver/chatroom/tagMembersCount.action"

Example success response

HTTP response in JSON

json"Content-Type": "application/json; charset=utf-8"
{
  "data": {
    "tag": "abc",
    "onlineUserCount":222
  },
  "code": 200
}

Status code

The status code returned in the response body. For more information, see Status codes.

Query the list of online members using tags

You can query online members using tags by calling this API.

If a user logs in on multiple devices, all login records are returned.

URL

httpPOST https://api.netease.im/nimserver/chatroom/tagMembersQuery.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

Request parameters

• For information about how to set the header in a POST request, see API Call methods.

• The settings of the body in a POST request:

Parameter	Type	Required	Description
roomid	Long	Yes	Chat room ID.
tag	string	Yes	Tag
endTime	Long	Yes	The start time of a query in descending order by time. A value of 0 indicates that the query starts from the current time to the earliest records
limit	int	Yes	The number of records returned, up to 100.

Example

cURL request example

curlcurl -X POST  -H 'appkey: fe416640c8e8a72734219e1847ad2547'  -H 'cache-control: no-cache'  -H 'checksum: 18f5435a7bf287af9150ad608797f75265495034'  -H 'content-type: application/x-www-form-urlencoded'   -H 'curtime: 1508481877'   -H 'nonce: 12345' -d 'tag=abc&roomid=3001&endTime=0&limit=100' "https://api.netease.im/nimserver/chatroom/tagMembersQuery.action"

Example success response

json"Content-Type": "application/json; charset=utf-8"
{
  "desc": {
    "data": [
      {
        "roomid": 111,
        "accid": "abc",
        "nick": "zlw",
        "avator": "http://nim.nos.netease.com/MTAxMTAwMg==xxx==",
        "ext": "ext",
        "type": "MANAGER",
        "level": 2,
        "onlineStat": true,
        "enterTime": "1487145487971",
        "blacklisted": true,
        "muted": true,
        "tempMuted": true,
        "tempMuteTtl": 120,
        "isRobot": true,
        "robotExpirAt": 120,
        "tags": "aaa",
        "notifyTargetTags": "{\"tag\": \"abc\"} and {\"tag\": \"def\"}"
      }
    ]
  },
  "code": 200
}

Status code

The status code returned in the response body. For more information, see Status codes.

Query message history by tag

You can query message history of a chat room by tag by calling this API.

URL

httpPOST  https://api.netease.im/nimserver/chatroom/queryTagHistoryMsg.action HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=utf-8

Request parameters

• For information about how to set the header in a POST request, see API Call methods.

• The settings of the body in a POST request:

Parameter	Type	Required	Description
roomid	Long	Yes	Chat room ID.
tags	String	Yes	Tags in JSONArray, example: ["tag1", "tag2"].
types	String	No	Message types in JSONArray, example [1,2,3]. By default, all types of messages are queried.
fromTime	Long	No	The start time of a query.
toTime	Long	No	The end time of a query.
limit	Integer	No	The number of returned messages. Up to 200. The default value is 200.
reverse	Integer	No	Whether the result is displayed in descending order by time.0: No (default), 1: Yes

Example

cURL request example

curlcurl -X POST 'https://api.netease.im/nimserver/history/queryTagHistoryMsg.action' -H 'AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3' -H 'Nonce: 4tgggergigwow323t23t' -H 'CurTime: 1443592222' -H 'CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86' -H 'Content-Type: application/x-www-form-urlencoded' -d 'roomId=10000&tags=["tag1","tag2","tag3"]&types=[0,1]&fromTime=1666241788000&toTime=1666251788000&limit=100&reverse=0'

Example success response

json"Content-Type": "application/json; charset=utf-8"
{
    "msgs": [
        {
            "msgid": "0fb86152-f9fb-9cbe-bcd9-9caed878dade", //消息id
            "from": "jiajia01", //ID of a message sender
            "type": 0,//Message type
            "sendtime": 1666072906119,//Time when the message was sent
            "body": {
                "msg": "this is message attachment 3" //Message content
            },
            "fromclienttype": 64 //Client type
        },
        {
            "msgid": "15459c99-666a-444b-3d50-3175f8cf5145",
            "from": "jiajia01",
            "type": 0,
            "sendtime": 1666072876187,
            "body": {
                "msg": "this is message attachment 2"
            },
            "fromclienttype": 64
        }
    ],
    "code": 200,
    "size": 2
}

Example error response

json"Content-Type": "application/json; charset=utf-8"
{
"code": 414,
"desc": "error roomId"  //Invalid chat room ID
}

json"Content-Type": "application/json; charset=utf-8"
{
"code": 403,
"desc": "search not enable"  // Search is disabled
}

Status code

The following status codes are related to responses of this API. For more status codes, see Status codes.

Status code	Description	Recommendation
200	Success	-
414	Parameter error	Check the format and restrictions of arguments based on the error message
403	Forbidden operation	Grant the permission of search for cloud messages.

Change the tag of participants

You can change the tag of a participant in chat rooms. If the tag of a participant is changed, The participant whose tag is changed is modified on all online devices, and all participants in a chat room are broadcasted.

URL

httpPOST  https://api.netease.im/nimserver/chatroom/updateChatRoomRoleTag.action HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=utf-8

Request parameters

• For information about how to set the header in a POST request, see API Call methods.

• The settings of the body in a POST request:

Parameter	Type	Required	Description
roomid	Long	Yes	Chat room ID.
tags	String	Yes	Multiple tags are allowed in JSONArray, for example, ["tag1", "tag2"].
accid	String	Yes	User ID
notifyTargetTags	String	No	Tags for notifications is a tag expression. If the user gets disconnected, all the participants with `notifyTargetTags` are notified.

Example

cURL request example

curlcurl -X POST 'https://api.netease.im/nimserver/chatroom/updateChatRoomRoleTag.action' -H 'AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3' -H 'Nonce: 4tgggergigwow323t23t' -H 'CurTime: 1443592222' -H 'CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86' -H 'Content-Type: application/x-www-form-urlencoded' -d 'roomId=10000&tags=["tag1","tag2","tag3"]&accid=tyuiu987655787987fs7f98sd&notifyTargetTags={"tag":"tag1"} and {"tag":"tag2"}'

Example success response

json"Content-Type": "application/json; charset=utf-8"
{"code":200}

Example error response

json"Content-Type": "application/json; charset=utf-8"
{
"code": 414,
"desc": "error roomId"  //Invalid chat room ID
}

json"Content-Type": "application/json; charset=utf-8"
{
"code": 404,
"desc": "chatroom role not exists"  //The role does not exists
}

Status code

The following status codes are related to responses of this API. For more status codes, see Status codes.

Status code	Description	Recommendation
200	Success	-
414	Parameter error	Check the format and restrictions of arguments based on the error message
404	User does not exist	check the user accid.