Manage tags

Update time: 2022/12/13 17: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 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

POST 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:

ParameterTypeRequiredDescription
roomid LongYes Chat room ID.
operator StringisThe account of an operator, The operator must be the creator or administrator
targetTag StringYesTarget tag
needNotify BooleanNoWhether a notification is sent when a user is muted. The default value is true.
notifyExt StringNoExtension field for notifications
muteDuration intYesThe duration for muting in seconds, up to 30 days, if the value is set to 0, a user is unmuted.< /td>
notifyTargetTags StringNoThe target tag expression for mute notifications, if unspecified, the notification will be sent to users with `targetTag`.< /td>

Example

cURL request example

curl -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

"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

POST 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:

ParameterTypeRequiredDescription
roomid LongYes Chat room ID.
tag stringYesTag

Example

cURL request example

curl -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

"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

POST 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:

ParameterTypeRequiredDescription
roomid LongYes Chat room ID.
tag stringYesTag
endTime LongYesThe 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 intYes The number of records returned, up to 100.

Example

cURL request example

curl -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

"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

POST  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:

ParameterTypeRequiredDescription
roomid LongYes Chat room ID.
tags StringYesTags in JSONArray, example: ["tag1", "tag2"].
types StringNoMessage types in JSONArray, example [1,2,3]. By default, all types of messages are queried.
fromTime LongNoThe start time of a query.
toTime LongNoThe end time of a query.
limit IntegerNoThe number of returned messages. Up to 200. The default value is 200.
reverse Integer NoWhether the result is displayed in descending order by time.0: No (default), 1: Yes

Example

cURL request example

curl -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

"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

"Content-Type": "application/json; charset=utf-8"
{
"code": 414,
"desc": "error roomId"  //Invalid chat room ID
}
"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

POST  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:

ParameterTypeRequiredDescription
roomid LongYes Chat room ID.
tags StringYesMultiple tags are allowed in JSONArray, for example, ["tag1", "tag2"].
accid StringYesUser ID
notifyTargetTags StringNoTags for notifications is a tag expression. If the user gets disconnected, all the participants with `notifyTargetTags` are notified.

Example

cURL request example

curl -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

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

Example error response

"Content-Type": "application/json; charset=utf-8"
{
"code": 414,
"desc": "error roomId"  //Invalid chat room ID
}
"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.
Was this page helpful?
Yes
No
  • Mute participants usting tags
  • URL
  • Request parameters
  • Example
  • cURL request example
  • Example success response
  • Status code
  • Query the number of online users with a specific tag
  • URL
  • Request parameters
  • Example
  • cURL request example
  • Example success response
  • Status code
  • Query the list of online members using tags
  • URL
  • Request parameters
  • Example
  • cURL request example
  • Example success response
  • Status code
  • Query message history by tag
  • URL
  • Request parameters
  • Example
  • cURL request example
  • Example success response
  • Example error response
  • Status code
  • Change the tag of participants
  • URL
  • Request parameters
  • Example
  • cURL request example
  • Example success response
  • Example error response
  • Status code