聊天室标签
更新时间: 2024/07/17 17:57:35
通过聊天室标签功能,可将聊天室消息向聊天室部分成员下发,也支持仅接收特定的消息。本文介绍 IM 服务端相关标签功能。
标签禁言
功能描述
将特定标签的登录用户设置为在特定时间段内禁言。
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¬ifyTargetTags={"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 |
此文档是否对你有帮助?