通过聊天室标签功能，可将聊天室消息向聊天室部分成员下发，也支持仅接收特定的消息。本文介绍 IM 服务端相关标签功能。

• 聊天室标签在 SDK 实例登录时设置。聊天室标签功能的具体介绍，请参见聊天室标签功能。
• 除本文介绍的相关 API 外，IM 服务端还支持在发送聊天室消息时通过notifyTargetTags参数设置将消息限制发送给哪些用户，如果缺失则会发给聊天室所有用户。详见发送聊天室消息。

标签禁言

功能描述

将特定标签的登录用户设置为在特定时间段内禁言。

URL

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

请求参数

• POST 请求中 Headers 的设置请参考API调用方式。

• POST 请求中 Body 的设置如下：

参数	类型	必须	说明
roomid	Long	是	聊天室ID
operator	string	是	操作者accid，必须是创建者或者管理员
targetTag	string	是	目标标签
needNotify	boolean	否	true/false，是否发送禁言通知，默认true
notifyExt	string	否	禁言通知通知扩展字段
muteDuration	int	是	禁言时长，单位秒，最长30天，若等于0表示取消禁言
notifyTargetTags	string	否	禁言通知的目标标签表达式，若缺失则发送给设置了targetTag的人

示例

cURL请求示例

curlcurl -X POST  -H 'appkey: fe416640**9e1847ad2547'  -H 'cache-control: no-cache'  -H 'checksum: 18f5435a7bf2**7f75265495034'  -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"

请求成功返回示例

json"Content-Type": "application/json; charset=utf-8"
{
    "code": 200,
    "desc": {
        "muteDuration": 100   //禁言时长，若取消禁言，则返回上次禁言的剩余禁言时长
    }
} 

状态码

该 API 在 HTTPS Body 中返回请求的状态码，状态码详情请参见状态码。

查询标签下的在线用户数

功能描述

查询某个标签下的在线人数。

单个账号多端登录情况下，在线用户数为 1。

URL

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

请求参数

• POST 请求中 Headers 的设置请参考API调用方式。

• POST 请求中 Body 的设置如下：

参数	类型	必须	说明
roomid	Long	是	聊天室ID
tag	string	是	标签

示例

cURL请求示例

curlcurl -X POST  -H 'appkey: fe416640c8**1847ad2547'  -H 'cache-control: no-cache'  -H 'checksum: 18f5435a7bf**97f75265495034'  -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"

请求成功返回示例

http 响应:json

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

状态码

该 API 在 HTTPS Body 中返回请求的状态码，状态码详情请参见状态码。

根据标签查询在线成员列表

功能描述

根据标签查询在线成员列表。

多端登录情况下同一在线成员会返回多条记录。

URL

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

请求参数

• POST 请求中 Headers 的设置请参考API调用方式。

• POST 请求中 Body 的设置如下：

参数	类型	必须	说明
roomid	Long	是	聊天室ID
tag	string	是	标签
endTime	Long	是	起始时间，逆序查询，若传0则表示从当前时间往前查
limit	int	是	条数，最多100

示例

cURL请求示例

curlcurl -X POST  -H 'appkey: fe416640c8e**e1847ad2547'  -H 'cache-control: no-cache'  -H 'checksum: 18f5435a7bf28**f75265495034'  -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"

请求成功返回示例

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
}

状态码

该 API 在 HTTPS Body 中返回请求的状态码，状态码详情请参见状态码。

根据标签查询历史消息

功能描述

根据聊天室标签（Tags）查询聊天室历史消息。

URL

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

请求参数

• POST 请求中 Headers 的设置请参考API调用方式。

• POST 请求中 Body 的设置如下：

参数	类型	必填	说明
roomId	Long	是	聊天室 ID
tags	String	是	标签 JSON 字符串 ["tag1", "tag2"]
types	String	否	消息类型 JSON 字符串 [1,2,3]，默认查询全部消息类型
fromTime	Long	否	检索开始时间
toTime	Long	否	检索结束时间
limit	Integer	否	查询数量，默认值和最大值都为 200
reverse	Integer	否	是否反向，0：否（默认），1：是

示例

cURL请求示例

curlcurl -X POST 'https://api.netease.im/nimserver/history/queryTagHistoryMsg.action' -H 'AppKey: go9dnk49bk**glw0803mgq3' -H 'Nonce: 4tggger**3t23t' -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'

请求成功返回示例

json"Content-Type": "application/json; charset=utf-8"
{
    "msgs": [
        {
            "msgid": "0fb86152-f9fb-9cbe-bcd9-9caed878dade", //消息id
            "from": "jiajia01", //消息发送者id
            "type": 0,//消息类型
            "sendtime": 1666072906119,//消息发送时间
            "body": {
                "msg": "this is message attachment 3" //消息内容
            },
            "fromclienttype": 64 //消息客户端类型
        },
        {
            "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
}

请求失败返回示例

"Content-Type": "application/json; charset=utf-8"
{
"code": 414,
"desc": "error roomId"  //聊天室id不合法
}

"Content-Type": "application/json; charset=utf-8"
{
"code": 403,
"desc": "search not enable"  //搜索未开启
}

状态码

该接口在 HTTPS Body 中返回请求的状态码，以下仅列出与接口业务相关的状态码。完整状态码请参见状态码。

状态码	说明	处理建议
200	请求成功	-
414	参数错误	根据提示信息，检查传入参数的格式和限制条件
403	禁止操作	请开启云端消息检索权限

修改聊天室用户标签

功能描述

修改聊天室用户的标签，修改 tag 后会通知被修改人的所有在线端并广播通知聊天室内所有用户。

URL

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

请求参数

• POST 请求中 Headers 的设置请参考API调用方式。

• POST 请求中 Body 的设置如下：

参数	类型	必填	说明
roomId	Long	是	聊天室 ID
tags	String	是	可设置多个标签，JSON 字符串 ["tag1", "tag2"]
accid	String	是	用户 ID
notifyTargetTags	String	否	通知目标用户的标签，是标签表达式，同时也会改变该连接掉线时的通知对象

示例

cURL请求示例

curlcurl -X POST 'https://api.netease.im/nimserver/chatroom/updateChatRoomRoleTag.action' -H 'AppKey: go9dnk49b**lw0803mgq3' -H 'Nonce: 4tggge**3t23t' -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"}'

请求成功返回示例

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

请求失败返回示例

"Content-Type": "application/json; charset=utf-8"
{
"code": 414,
"desc": "error roomId"  //聊天室id不合法
}

"Content-Type": "application/json; charset=utf-8"
{
"code": 404,
"desc": "chatroom role not exists"  //聊天室角色不存在
}

状态码

该接口在 HTTPS Body 中返回请求的状态码，以下仅列出与接口业务相关的状态码。完整状态码请参见状态码。

状态码	说明	处理建议
200	请求成功	-
414	参数错误	根据提示信息，检查传入参数的格式和限制条件
404	聊天室用户不存在	检查用户 accid