跳转至

属性自定义

聊天室属性设置

为指定聊天室以 Key、Value 方式自定义设置属性信息,此服务需要在开发者后台开通 IM 商用版后,开通使用。

应用场景

1、语音直播室场景,可用于做会场属性的同步,如房间内的成员属性,麦位上的人员等等。

2、狼人杀等卡牌类的游戏场景,可用于记录用户的角色,牌局状态等。

警告

每个聊天室中,最多允许设置 100 个属性信息,以 Key、Value 的方式进行存储,每个聊天室中每秒钟最多允许操作 Key、Value 100 次。

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

设置属性

方法名:/chatroom/entry/set

签名方法:请参考 通用 API 接口签名规则

URL:http(s)://api-cn.ronghub.com/chatroom/entry/set.[format]

[format] 表示返回格式,可以为 jsonxml,注意不要带 [ ]。

HTTP 方法:POST

表单参数

名称 类型 说明
chatroomId String 聊天室 Id
userId String 操作用户 Id。必须为聊天室中用户,否则设置不成功
key String 聊天室属性名称,Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式,大小写敏感。最大长度 128 字符
value String 聊天室属性对应的值,最大长度 4096 个字符
autoDelete Boolean 用户退出聊天室后,是否删除此 Key 值。为 true 时删除此 Key 值,为 false 时用户退出后不删除此 Key,默认为 false
objectName String 通知消息类型,设置属性后是否发送通知消息,如需要发送则设置为 RC:chrmKVNotiMsg 或其他自定义消息,为空或不传时不向聊天室发送通知消息,默认为不发送。(可选)
content String 通知消息内容,JSON 结构,当 objectName 为 RC:chrmKVNotiMsg 时,content 必须包含 type、key、value 属性,详细查看 RC:chrmKVNotiMsg 结构说明

返回值

名称 类型 说明
code Int 返回码,200 为正常。

JSON 格式:

{"code":200}

XML 格式:

<xml><code>200</code></xml>

返回值请参考 API 方法返回值说明

示例

HTTP 请求:

POST /chatroom/entry/set.json HTTP/1.1
Host: api-cn.ronghub.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=true&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 响应:

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

{"code":200}

删除属性

方法名:/chatroom/entry/remove

签名方法:请参考 通用 API 接口签名规则

URL:http(s)://api-cn.ronghub.com/chatroom/entry/remove.[format]

[format] 表示返回格式,可以为 jsonxml,注意不要带 [ ]。

HTTP 方法:POST

表单参数

名称 类型 说明
chatroomId String 聊天室 Id
userId String 操作用户 Id。必须为聊天室中用户,否则设置不成功
key String 聊天室属性名称,Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式,大小写敏感。最大长度 128 字
objectName String 通知消息类型,设置属性后是否发送通知消息,如需要发送则设置为 RC:chrmKVNotiMsg 或其他自定义消息,为空或不传时不向聊天室发送通知消息,默认为不发送。(可选)
content String 通知消息内容,JSON 结构,当 objectName 为 RC:chrmKVNotiMsg 时,content 必须包含 type、key、value 属性,详细查看 RC:chrmKVNotiMsg 结构说明

返回值

名称 类型 说明
code Int 返回码,200 为正常。

JSON 格式:

{"code":200}

XML 格式:

<xml><code>200</code></xml>

返回值请参考 API 方法返回值说明

示例

HTTP 请求:

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

chatroomId=kvchatroom2&userId=jrT1igbKr

HTTP 响应:

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

{"code":200}

获取属性

方法名:/chatroom/entry/query

签名方法:请参考 通用 API 接口签名规则

URL:http(s)://api-cn.ronghub.com/chatroom/entry/query.[format]

[format] 表示返回格式,可以为 jsonxml,注意不要带 [ ]。

HTTP 方法:POST

表单参数

名称 类型 说明
chatroomId String 聊天室 Id
keys String 批量获取指定聊天室中的 Key 值,最多上限为 100 个,为空时获取全部 key 值。

返回值

名称 类型 说明
code Int 返回码,200 为正常。
key String 设置的属性名。
value String 属性对应的内容。
userId String 最后一次设置此 Key 的用户 Id。
autoDelete Int 用户退出聊天室后是否删除此 Key,0 为不删除、1为删除。
lastSetTime String 最近一次设置 Key 的时间。

JSON 格式:

{
	"code":200,
	"keys":
	[{"key":"key1","value":"value1","userId":"2121","autoDelete":0,"lastSetTime":"2121"},
	{"key":"key2","value":"value2","userId":"4343","autoDelete":1," lastSetTime":"2121"}]
}

返回值请参考 API 方法返回值说明

示例

HTTP 请求:

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

chatroomId=kvchatroom2&userId=Lnq9MJsPY

HTTP 响应:

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

{
	"code":200,
	"keys":
	[{"key":"key1","value":"value1","userId":"2121","autoDelete":0,"lastSetTime":"2121"},
	{"key":"key2","value":"value2","userId":"4343","autoDelete":1," lastSetTime":"2121"}]
}