Manage tags
Update time: 2022/12/13 09:34:40
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 withoutnotifyTargetTags
are sent to all users in the chat room. For more information, see Send messages。
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.
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¬ifyTargetTags={"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. |