概述

网易云信 IM 支持聊天室队列中的元素管理功能。通过定义队列中 key 和 value 的值，来定义聊天室队列中的元素，可以对元素进行多样化的管理。

API 使用限制

目前聊天室队列通知（消息）的接收，有以下流控机制。

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

添加或更新元素

功能描述

用户可以在聊天室有序队列中添加或更新元素。

若该元素由用户 A 添加，之后再由用户 B 更新，则该元素的所有者为用户 B。

URL

httpPOST https://api.yunxinapi.com/nimserver/chatroom/queueOffer.action 

请求参数

• POST 请求中 Headers 的设置请参考 接口概述。

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

  参数	类型	是否必选	说明
  roomid	Long	是	聊天室 ID。
  key	String	是	元素 key，最大长度 128 字符。
  value	String	是	元素内容，最大长度 4096 字符。
  operator	String	否	操作者账号，操作者必须在线（在聊天室中）。默认为该聊天室的创建者。 若指定的 operator 不在线（不在聊天室中）时，operator 必须为聊天室创建者账号才能成功添加或更新元素，否则返回 403 错误。 若 operator 账号不存在，会返回 404 错误。
  transient	Boolean	否	当 operator 从该聊天室掉线或者离开该聊天室时，添加的元素是否需要删除。 true：需要删除；false：不需要删除（默认）。 如果设置为 true，那么 operator 当前不在该聊天室内，则会返回 302 错误。
  highPriority	Integer	否	是否设置为高优先级消息。 0：否（默认）；1：是。
  highPriorityPolicy	Integer	否	高优先级消息策略：针对高优先级消息，超过流控后是自动降级为普通消息还是直接返回 416 错误码。 0：降级为普通消息（默认）；1：返回 416 错误码。

示例

请求示例（curl）

curlcurl -X POST -H "CheckSum: 32dc17d0190f37***9bbf049c9367e7" -H "AppKey: fe416640***47ad2547" -H "Nonce: 1" -H "CurTime: 1451200147" -H "Cache-Control: no-cache" -H "Postman-Token: b9550dce-74c1-9606-0084-71dd8ec201b6" -H "Content-Type: application/x-www-form-urlencoded" -d 'roomid=36&key=1111&value=66666' "https://api.yunxinapi.com/nimserver/chatroom/queueOffer.action"

请求成功返回示例

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

请求失败返回示例

JSON{
    "Content-Type": "application/json; charset=utf-8",
    "code": 414,
    "desc": "roomid not exist"
}

状态码

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

状态码	说明	处理建议
200	请求成功	-
302	operator 当前不在该聊天室内	-
403	禁止操作： 未开启聊天室权限	开通聊天室功能
404	operator 对应的账号不存在	-
414	参数错误	根据提示信息，检查传入参数的格式和限制条件
416	频控限制或异常错误	降低访问频率
500	服务出错	-

批量添加队列元素

功能描述

用户可以在聊天室队列中批量添加元素。

• 若聊天室队列未初始化，则自动初始化队列，并收到队列初始化抄送信息。
• 若队列元素所属账号不在线且非聊天室创建者，则添加元素失败。

URL

httpPOST https://api.yunxinapi.com/nimserver/chatroom/queueBatchOffer.action  

请求参数

• POST 请求中 Headers 的设置请参考 接口概述。
• POST 请求中 Body 的设置如下：

参数	类型	是否必选	说明
roomid	Long	是	聊天室 ID。
operator	String	否	批量添加元素的操作者账号。不填默认为聊天室创建者。
transient	Boolean	否	队列元素所有者从该聊天室掉线或者离开该聊天室时，添加的元素是否需要删除。 true：需要删除；false：不需要删除（默认）。 如果设置为 true，且所有者当前不在该聊天室内，则添加元素失败。 若未配置单个 elements 的 transient 参数，则使用该字段的配置选择。
elements	Object	是	添加元素的 key-value 对，最多 20 个。格式为 JSONArray，示例： [ { "key": "key01", //元素 key "value": "{"priority":10}", //元素 value "accid":"user01", //元素所属者账号，不填则默认 operator "transient":true //离开聊天室是否删除元素 } ]
needNotify	String	否	是否需要发送更新通知，默认为 true，需要通知。若设置为 false，则不触发频控。
notifyExt	String	否	通知事件扩展字段，最大长度 2048 字符。
highPriority	Integer	否	是否设置为高优先级消息。 0：否（默认）；1：是。
highPriorityPolicy	Integer	否	高优先级消息策略：针对高优先级消息，超过流控后是自动降级为普通消息还是直接返回 416 错误码。 0：降级为普通消息（默认）；1：返回 416 错误码。

示例

请求示例（curl）

curlcurl -X POST -H 'appkey: fe416640***47ad2547' -H 'cache-control: no-cache' -H 'checksum: 18f54***f75265495034' -H 'content-type: application/x-www-form-urlencoded' -H 'curtime: 1508481877' -H 'nonce: 12345' --data-urlencode 'roomid=64' --data-urlencode 'operator=user01' --data-urlencode 'transient=false' --data-urlencode 'needNotify=false' --data-urlencode 'elements=[{"key":"key01","value":"{\"priority\":10}","accid":"user01","transient":true}]' "https://api.yunxinapi.com/nimserver/chatroom/queueBatchOffer.action"

请求成功返回示例

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

JSON{
    "Content-Type": "application/json; charset=utf-8",
    "code": 200,
    "desc": {
        "failedKeys": [  // 添加失败的元素key
            "key01"
        ]
    }
}

请求失败返回示例

JSON{
    "Content-Type": "application/json; charset=utf-8",
    "code": 414,
    "desc": "roomid not exist"
}

状态码

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

状态码	说明	处理建议
200	请求成功	-
403	禁止操作： 未开启聊天室权限	开通聊天室功能
414	参数错误	根据提示信息，检查传入参数的格式和限制条件
416	频控限制或异常错误	降低访问频率
500	服务出错	-

批量更新队列元素

功能描述

用户可以在聊天室队列中批量更新元素。

若该元素由用户 A 添加，之后再由用户 B 更新，则该元素的所有者为用户 B。

URL

httpPOST https://api.yunxinapi.com/nimserver/chatroom/queueBatchUpdateElements.action  

请求参数

• POST 请求中 Headers 的设置请参考 接口概述。

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

  参数	类型	是否必选	说明
  roomid	Long	是	聊天室 ID。
  operator	String	是	批量更新元素的操作者账号。操作者必须为该聊天室的创建者或管理员。
  elements	Object	是	更新的元素 key-value 对，最多 200 个。示例：{"k1":"v1","k2":"v2"}。
  needNotify	String	否	是否需要发送更新通知，默认为 true，需要通知。若设置为 false，则不触发频控。
  notifyExt	String	否	通知事件扩展字段，最大长度 2048 字符。
  highPriority	Integer	否	是否设置为高优先级消息。 0：否（默认）；1：是。
  highPriorityPolicy	Integer	否	高优先级消息策略：针对高优先级消息，超过流控后是自动降级为普通消息还是直接返回 416 错误码。 0：降级为普通消息（默认）；1：返回 416 错误码。

示例

请求示例（curl）

curlcurl -X POST -H 'appkey: fe4166***47ad2547' -H 'cache-control: no-cache' -H 'checksum: 18f5435a***75265495034' -H 'content-type: application/x-www-form-urlencoded' -H 'curtime: 1508481877' -H 'nonce: 12345' -d 'roomid=18&operator=zhouliangwei&elements=%7b%22k1%22%3a%22v1%22%2c%22k2%22%3a%22v2%22%7d' "https://api.yunxinapi.com/nimserver/chatroom/queueBatchUpdateElements.action"

请求成功返回示例

JSON{
  "Content-Type": "application/json; charset=utf-8",
  "code": 200,
  "desc": {
    "noExistElementKey": [
      "k1"
    ]
  }
}

请求失败返回示例

JSON{
    "Content-Type": "application/json; charset=utf-8",
    "code": 414,
    "desc": "roomid not exist"
}

状态码

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

状态码	说明	处理建议
200	请求成功	-
403	禁止操作： 未开启聊天室权限 operator 不是聊天室创建者或管理员	根据对应提示信息做出处理
414	参数错误	根据提示信息，检查传入参数的格式和限制条件
416	频控限制或异常错误	降低访问频率
500	服务出错	-

排序列出队列中所有元素

URL

httpPOST https://api.yunxinapi.com/nimserver/chatroom/queueList.action  

请求参数

• POST 请求中 Headers 的设置请参考 接口概述。

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

  参数	类型	是否必选	说明
  roomid	Long	是	聊天室 ID。

示例

请求示例（curl）

curlcurl -X POST -H "CheckSum: 37dc87d***kbf049c9367e7" -H "AppKey: fe416640c8e8a7***47ad2547" -H "Nonce: 1" -H "CurTime: 1451200147" -H "Content-Type: application/x-www-form-urlencoded" -d 'roomid=36' "https://api.yunxinapi.com/nimserver/chatroom/queueList.action"

返回示例

JSON{
  "Content-Type": "application/json; charset=utf-8",
  "desc": {
    "list": [
      {
        "33333": "33333"
      }
    ]
  },
  "code": 200
}

状态码

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

从队列中取出元素

URL

httpPOST https://api.yunxinapi.com/nimserver/chatroom/queuePoll.action  

请求参数

• POST 请求中 Headers 的设置请参考 接口概述。

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

  参数	类型	是否必选	说明
  roomid	Long	是	聊天室 ID。
  key	String	是	elementKey，最大长度 128 字符。若不传，则表示去除队列的第一个元素。
  highPriority	Integer	否	是否设置为高优先级消息。 0：否（默认）；1：是。
  highPriorityPolicy	Integer	否	高优先级消息策略：针对高优先级消息，超过流控后是自动降级为普通消息还是直接返回 416 错误码。 0：降级为普通消息（默认）；1：返回 416 错误码。

示例

请求示例（curl）

curlcurl -X POST -H "CheckSum: 32dc17d0190f3**bbf049c9367e7" -H "AppKey: fe416640c8e8a7***47ad2547" -H "Nonce: 1" -H "CurTime: 1451200147" -H "Cache-Control: no-cache" -H "Postman-Token: b9550dce-74c1-9606-0084-71dd8ec201b6" -H "Content-Type: application/x-www-form-urlencoded" -d 'roomid=36&key=333334444' "https://api.yunxinapi.com/nimserver/chatroom/queuePoll.action"

请求成功返回示例

JSON{
  "Content-Type": "application/json; charset=utf-8",
  "desc": {
    "value": "66666",
    "key": "1111"
  },
  "code": 200
}

请求失败返回示例

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

状态码

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

状态码	说明	处理建议
200	请求成功	-
403	禁止操作： 未开启聊天室权限	开通聊天室功能
414	参数错误	根据提示信息，检查传入参数的格式和限制条件
416	频控限制或异常错误	降低访问频率
500	服务出错	-

获取指定的队列元素

功能描述

根据指定的聊天室队列元素 key 列表获取元素信息。

URL

httpPOST https://api.yunxinapi.com/nimserver/chatroom/queueMultiGet.action  

请求参数

• POST 请求中 Headers 的设置请参考 接口概述。

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

  参数	类型	是否必选	说明
  roomid	Long	是	聊天室 ID。
  keys	String	是	需要查询的队列元素 key 列表，最大 100 个，格式为 JSONArray，示例：["key1","key2","key3"]。

示例

请求示例（curl）

curlcurl -X POST -H 'appkey: fe4***d2547' -H 'cache-control: no-cache' -H 'checksum: 18f5***65495034' -H 'content-type: application/x-www-form-urlencoded' -H 'curtime: 1508481877' -H 'nonce: 12345' -d 'roomid=64&keys=%5B%22key1%22%2C%22key2%22%2C%22key3%22%5D' "https://api.yunxinapi.com/nimserver/chatroom/queueMultiGet.action"

返回示例

JSON{
    "Content-Type": "application/json; charset=utf-8",
    "code": 200,
    "desc": {
        "list": [
            {
                "key1": "value1"
            },
            {
                "key2": "value2"
            },
            {
                "key3": "value3"
            }
        ]
    }
}

状态码

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