Set Chatroom Custom Attributes (KV)

Set a custom attribute key-value (KV) pair in a specified chatroom. This API requires the user ID of the operator to be passed as the owner of the KV pair.

When a chatroom is destroyed, all custom attributes within it are also destroyed.

Enable the Service

Before using the Chatroom Custom Attributes (KV) feature, ensure that the service has been enabled for the current App Key. For details, refer to Chatroom Custom Attributes Overview.

If the service is not enabled, the Server API will return error code 1009. Note that if the API request frequency exceeds the limit due to continuous requests when the service is not enabled, the Server API will return an HTTP 429 Too Many Requests error (error code 1008).

Request Method

POST: https://Data Center Domain/chatroom/entry/set.json

Rate Limit: Up to 100 KV pairs can be operated per second, sharing the rate limit quota with the batch setting API /chatroom/entry/batch/set.json. If only the single attribute setting API is used, it can be called 100 times per second.

Signature Rule: All server API requests require signature verification. For details, refer to API Request Signature.

Request Body Parameters

The HTTP request body data format is application/x-www-form-urlencoded, and the following HTTP form parameters are supported:

Parameter	Type	Required	Description
chatroomId	String	Yes	The chatroom ID.
userId	String	Yes	The operator's user ID. Users outside the chatroom can set attributes via the Server API.
key	String	Yes	The name of the chatroom attribute. The key supports a combination of uppercase and lowercase letters, numbers, and special symbols + = - _, and is case-sensitive. The maximum length is 128 characters. Each chatroom allows up to 100 Key-Value pairs to be set.
value	String	Yes	The value corresponding to the chatroom attribute. The maximum length is 4096 characters.
autoDelete	Int	No	Whether to delete this key-value pair when the operator exits the chatroom. Set to 1 to delete the key and its corresponding value, or 0 to retain it after the user exits. The default is 0.
objectName	String	No	The message type for the chatroom attribute change notification, usually the built-in message type RC:chrmKVNotiMsg, or a custom message type. If this field is provided, a message will be sent when the chatroom attribute changes. Note: Older versions of the client SDK (Android/iOS < 4.0.2, Web < 3.0.6) rely on this notification message to synchronize chatroom attribute changes from the server.
content	String	No	The message content for the chatroom attribute change notification. JSON structure. When objectName is RC:chrmKVNotiMsg, the content must include the type, key, and value attributes. For a detailed description of the RC:chrmKVNotiMsg message structure, refer to Chatroom Attribute Notification Message.

Request Example

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

Response

The HTTP response body contains a JSON object with the following structure:

Return Value	Type	Description
code	Number	The return code. 200 indicates success.

Response Example

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

{"code":200}