API 参考
圈组

聊天室队列管理

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

网易云信 IM 支持聊天室队列服务,可以对聊天室队列进行管理。

聊天室队列指聊天室(房间)中由多个元素(key-value 键值对)构成的队列,应用于直播间中的连麦场景和礼物队列展示等场景。

初始化队列

URL

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

请求参数

  • POST 请求中 Headers 的设置请参考接口概述
  • POST 请求中 Body 的设置如下:
参数类型必须说明
roomid long 聊天室id
sizeLimit long 队列长度限制,0~1000

示例

请求示例(curl)

curlcurl -X POST -H "CheckSum: 32dc1***049c9367e7" -H "AppKey: fe41***847ad2547" -H "Nonce: 1" -H "CurTime: 1451200147" -H "Cache-Control: no-cache" -H "Postman-Token: f2600d32-4a27-fabc-3295-9a339960839e" -H "Content-Type: application/x-www-form-urlencoded" -d 'roomid=38&sizeLimit=10' "https://api.netease.im/nimserver/chatroom/queueInit.action"

返回示例

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

状态码

上述接口在 HTTPS Body 中返回请求的状态码,状态码详情请参见状态码

删除清理队列

功能描述

用户可以删除清理整个聊天室队列,删除后会收到相关的队列通知消息。

API 使用限制

目前聊天室队列通知(消息)的接收,有以下流控机制。

  • 针对普通通知(消息),聊天室用户每秒至多可接收 20 条,超过部分会因为流控随机丢弃。为避免丢失重要消息(通常为服务端消息),可将下文请求参数中的 highPriority 参数设置为 true 实现高优先级接收服务端消息,进而保证高优先级消息流控上限内的重要消息不丢失。
  • 针对高优先级通知(消息),每秒至多接收 10 条,超过部分无法保证不丢失。可通过下文请求参数中的 highPriorityPolicy 参数设置超出限制后自动转为普通消息或者返回 416 错误码。

URL

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

请求参数

  • POST 请求中 Headers 的设置请参考接口概述
  • POST 请求中 Body 的设置如下:
参数类型必须说明
roomid Long聊天室 ID
highPriority Integer 是否设置为高优先级消息
0:否(默认);1:是高优先级消息
highPriorityPolicy Integer 高优先级消息策略:针对高优先级消息,超过流控后是自动降级为普通消息还是返回 416 错误码
0:降级为普通消息(默认);1:返回 416 错误码

示例

请求示例(curl)

curlcurl -X POST -H "CheckSum: 32dc17d**9bbf049c9367e7" -H "AppKey: fe416640**47ad2547" -H "Nonce: 1" -H "CurTime: 1451200147" -H "Cache-Control: no-cache" -H "Postman-Token: 2f40cf61-381e-6fd6-6169-001a9d389df3" -H "Content-Type: application/x-www-form-urlencoded" -d 'roomid=36&key=k2&value=v2' "https://api.netease.im/nimserver/chatroom/queueDrop.action"

请求成功返回示例

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

请求失败返回示例

"Content-Type": "application/json; charset=utf-8"
{
"code": 414,  // 参数错误
"desc": "roomid not exsit" 
}

状态码

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

状态码 说明 处理建议
200 请求成功 -
403 禁止操作:
未开启聊天室权限
开通聊天室功能
414 参数错误 根据提示信息,检查传入参数的格式和限制条件
416 频控限制或异常错误 降低访问频率
500 服务出错 -
此文档是否对你有帮助?
有帮助
去反馈
  • 初始化队列
  • URL
  • 请求参数
  • 示例
  • 请求示例(curl)
  • 返回示例
  • 状态码
  • 删除清理队列
  • 功能描述
  • API 使用限制
  • URL
  • 请求参数
  • 示例
  • 请求示例(curl)
  • 请求成功返回示例
  • 请求失败返回示例
  • 状态码