API 参考
圈组

聊天室标签

更新时间: 2024/07/17 17:57:35

通过聊天室标签功能,可将聊天室消息向聊天室部分成员下发,也支持仅接收特定的消息。本文介绍 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 booleantrue/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
此文档是否对你有帮助?
有帮助
去反馈
  • 标签禁言
  • 功能描述
  • URL
  • 请求参数
  • 示例
  • cURL请求示例
  • 请求成功返回示例
  • 状态码
  • 查询标签下的在线用户数
  • 功能描述
  • URL
  • 请求参数
  • 示例
  • cURL请求示例
  • 请求成功返回示例
  • 状态码
  • 根据标签查询在线成员列表
  • 功能描述
  • URL
  • 请求参数
  • 示例
  • cURL请求示例
  • 请求成功返回示例
  • 状态码
  • 根据标签查询历史消息
  • 功能描述
  • URL
  • 请求参数
  • 示例
  • cURL请求示例
  • 请求成功返回示例
  • 请求失败返回示例
  • 状态码
  • 修改聊天室用户标签
  • 功能描述
  • URL
  • 请求参数
  • 示例
  • cURL请求示例
  • 请求成功返回示例
  • 请求失败返回示例
  • 状态码