跳到主要内容

设置聊天室属性(KV)

在指定聊天室中设置一个自定义属性 KV 对。该接口要求同时传入操作用户 ID,作为该 KV 对的所属用户。

聊天室销毁后,聊天室中的自定义属性同时销毁。

开通服务

使用聊天室属性(KV) 功能前,请确认已为当前 App Key 开通相关服务。详见聊天室属性概述

如未开通服务,Server API 将返回 1009 错误。注意,在未开通服务时,如果连续请求导致 API 请求频率超过限制,Server API 会返回 HTTP 429 Too Many Requests 错误(错误码为 1008)。

请求方法

POST: https://数据中心域名/chatroom/entry/set.json

频率限制: 每秒钟限操作 100 对 KV,与批量设置接口 /chatroom/entry/batch/set.json 共享限频配额。如果仅使用设置单个属性的 API,则一秒可调用 100 次。

签名规则: 所有服务端 API 请求均需要进行规则校验,详见 API 请求签名

正文参数

HTTP 请求正文数据格式为 application/x-www-form-urlencoded,支持以下 HTTP 表单参数:

参数类型必传说明
chatroomIdString聊天室 ID。
userIdString操作用户 ID。通过 Server API 非聊天室中用户可以进行设置。
keyString聊天室属性名称,Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式,大小写敏感。最大长度 128 字符。每个聊天室中,最多允许设置 100 个属性 Key-Value 对。
valueString聊天室属性对应的值,最大长度 4096 个字符。
autoDeleteInt属性的操作用户退出聊天室后,是否删除此 Key 值。为 1 时删除此 Key 值和对应的 Value,为 0 时用户退出后不删除,默认为 0。
objectNameString聊天室属性变化通知消息的消息类型,一般为内置消息类型 RC:chrmKVNotiMsg,也可以是其他自定义消息类型。如果传入该字段,则在聊天室属性变化时发送一条消息。

注意:旧版客户端 SDK(Android/iOS < 4.0.2、Web < 3.0.6)依赖该通知消息从服务端同步聊天室属性变化。
contentString聊天室属性变化通知消息的消息内容。JSON 结构,当 objectName 为 RC:chrmKVNotiMsg 时,content 必须包含 type、key、value 属性。RC:chrmKVNotiMsg 消息结构的详细说明请参见 聊天室属性通知消息

请求示例

POST /chatroom/entry/set.json HTTP/1.1
Host: api.rong-api.com
App-Key: uwd1c0sxdlx2
Nonce: 14314
Timestamp: 1408710653491
Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8
Content-Type: application/x-www-form-urlencoded

chatroomId=kvchatroom2&userId=Lnq9MJsPY&key=huihui&value=555&autoDelete=0&objectName=RC%3AchrmKVNotiMsg&content=%7B%22key%22%3A%22keyli%22%2C%22value%22%3A%225%22%2C%22type%22%3A%221%22%7D&extra=111111

返回结果

HTTP 响应正文包含具有以下结构的 JSON 对象:

返回值返回类型说明
codeNumber返回码,200 为正常。

返回结果示例

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"code":200}