Chatroom Attribute Management (KV)

The chatroom attribute (KV) management interface is used to set custom attributes in a specified chatroom.

In voice live streaming chatroom scenarios, this feature can be utilized to record the attributes of each mic position in the chatroom. In card game scenarios like Werewolf, it can be used to record user roles and game states.

Functional Limitations

tip

• When a chatroom is destroyed, its custom attributes are also destroyed.
• Each chatroom allows a maximum of 100 attribute entries, stored in Key-Value pairs.
• The client SDK does not limit the operation frequency of chatroom attribute KV. It is recommended to keep the Key-Value operation frequency at 100 times or less per second per chatroom (operating 100 KVs in one second is equivalent to 100 operations).

Service Activation

To use the chatroom attribute (KV) interface, you need to activate the chatroom custom attributes service. You can enable this service by visiting the Basic features page in the Console.

If a server callback URL is configured, the RC server will synchronize changes in chatroom attributes (such as setting, deleting, or clearing all attributes) to the specified callback address. For more details, refer to the server documentation Chatroom Attribute Synchronization (KV).

Setting Up Chatroom KV Listener

Example call: addEventListener(Events.CHATROOM, listener)

Call addEventListener

const listener = (event) => {
  if (event.rejoinedRoom) {
    console.log('SDK internal reconnection chatroom info:', event.rejoinedRoom)
  }
  if (event.updatedEntries) {
    console.log('Detected chatroom KV updates:', event.updatedEntries)
  }
  if (event.userChange) {
    console.log('User join/exit notifications:', event.userChange)
  }
  if (event.chatroomDestroyed) {
    console.log('Chatroom destroyed:', event.chatroomDestroyed)
  }
}
RongIMLib.addEventListener(Events.CHATROOM, listener)

Getting a Single Attribute

Call getChatRoomEntry to retrieve a single attribute.

const chatRoomId = "chatroom ID";
const key = "name";

RongIMLib.getChatRoomEntry(chatRoomId, key).then(res => {
    // Successfully retrieved a single chatroom attribute
    if (res.code === 0) {
        console.log(res.code, res.data)
    } else {
        console.log(res.code, res.msg)
    }
}).catch(error => {
    console.log(error)
})

Parameter	Type	Description
chatRoomId	string	Chatroom ID
key	string	Chatroom attribute name. Key supports a combination of uppercase and lowercase letters, numbers, and special symbols + = - _, with a maximum length of 128 characters

Getting All Attributes

Call getAllChatRoomEntries to retrieve all attributes.

const chatRoomId = "chatroom ID";
RongIMLib.getAllChatRoomEntries(chatRoomId).then(res => {
    // Successfully retrieved all chatroom attributes
    if (res.code === 0) {
        console.log(res.code, res.data)
    } else {
        console.log(res.code, res.msg)
    }
}).catch(error => {
    console.log(error)
})

Setting a Single Attribute

Call setChatRoomEntry to set an attribute.

const entry = {
    key: 'key',
    value: 'value',
    notificationExtra: 'extra',
    isAutoDelete: true,
    isSendNotification: false
}
RongIMLib.setChatRoomEntry(chatRoomId, entry).then(res => {
    // Successfully set a single chatroom attribute
    if(res.code === 0){
        console.log(res.code)
    } else {
        console.log(res.code, res.msg)
    }
}).catch(error => {
    console.log(error)
})

Parameter	Type	Description
chatRoomId	String	Chatroom ID
key	String	Chatroom attribute name. Key supports a combination of uppercase and lowercase letters, numbers, and special symbols + = - _, with a maximum length of 128 characters
value	String	The value corresponding to the chatroom attribute, with a maximum length of 4096 characters
isSendNotification	Boolean	Whether to send a notification message after successful setting
isAutoDelete	Boolean	Whether to clear this attribute when the user exits the chatroom
notificationExtra	String	Additional information carried in the RC:chrmKVNotiMsg message

Force Setting a Single Attribute

Force setting a single chatroom attribute. This can be used to modify attribute values created by others. Call forceSetChatRoomEntry to force set a chatroom attribute. It is stored in the form of key = value. If the key does not exist, it adds the attribute; if the key exists, it updates the attribute value. Using force setting allows you to modify attribute values created by others.

const entry = {
    key: 'key',
    value: 'value',
    notificationExtra: 'extra',
    isAutoDelete: true,
    isSendNotification: false
}
RongIMLib.forceSetChatRoomEntry(chatRoomId, entry).then(res => {
    // Successfully force set a single chatroom attribute
    if(res.code === 0){
        console.log(res.code)
    } else {
        console.log(res.code, res.msg)
    }
}).catch(error => {
    console.log(error)
})

Parameter	Type	Description
chatRoomId	String	Chatroom ID
key	String	Chatroom attribute name. Key supports a combination of uppercase and lowercase letters, numbers, and special symbols + = - _, with a maximum length of 128 characters
value	String	The value corresponding to the chatroom attribute, with a maximum length of 4096 characters
isSendNotification	Boolean	Whether to send a notification message after successful setting
isAutoDelete	Boolean	Whether to clear this attribute when the user exits the chatroom
notificationExtra	String	Additional information carried in the RC:chrmKVNotiMsg message

Batch Setting Attributes

tip

Starting from SDK version 5.3.4, this interface also supports force setting multiple attribute values through the isForce property. Force setting can directly overwrite attribute values created by others.

Call setChatRoomEntries to batch set chatroom attributes.

const entries = [{key: '',value: ''}]
const options = {
    entries,
    isAutoDelete:true, // Whether to clear this attribute when the user exits the chatroom
    isForce: true // Whether to force overwrite
}
RongIMLib.setChatRoomEntries(chatRoomId, options).then(res => {
    // Successfully set chatroom attributes
    if(res.code === 0){
        console.log(res.code)
    } else {
        console.log(res.code, res.msg)
    }
}).catch(error => {
    console.log(error)
})

Parameter	Type	Description
chatRoomId	String	Chatroom ID
options.entries	Array	A collection of chatroom attribute key-value pairs. Key supports a combination of uppercase and lowercase letters, numbers, and special symbols + = - _, with a maximum length of 128 characters. The value corresponding to the chatroom attribute has a maximum length of 4096 characters
options.isAutoDelete	Boolean	Whether to clear this attribute when the user exits the chatroom
options.isForce	Boolean	Whether to force overwrite (this property requires SDK version ≧ 5.3.4)

Deleting a Single Attribute

Call removeChatRoomEntry to delete a chatroom custom attribute. Only attributes created by the current user can be deleted.

const chatRoomId = 'chatroom ID'
const entry = {
    key: key,
    notificationExtra: extra,
    isSendNotification: isSendNotification
}
RongIMLib.removeChatRoomEntry(chatRoomId, entry).then(res => {
    // Successfully deleted a single chatroom attribute
    if(res.code === 0){
        console.log(res.code)
    } else {
        console.log(res.code, res.msg)
    }
}).catch(error => {
    console.log(error)
})

Parameter	Type	Description
chatRoomId	String	Chatroom ID
key	String	Chatroom attribute name. Key supports a combination of uppercase and lowercase letters, numbers, and special symbols + = - _, with a maximum length of 128 characters
isSendNotification	Boolean	Whether to send a notification message after successful deletion
notificationExtra	String	Additional information carried in the RC:chrmKVNotiMsg message

Force Deletion

Call forceRemoveChatRoomEntry to force delete a chatroom custom attribute. Attributes created by others can be deleted.

const chatRoomId = 'chatroom ID'
const entry = {
    key: key,
    notificationExtra: extra,
    isSendNotification: isSendNotification
}
RongIMLib.forceRemoveChatRoomEntry(chatRoomId, entry).then(res => {
    // Successfully force deleted a chatroom attribute
    if(res.code === 0){
        console.log(res.code)
    } else {
        console.log(res.code, res.msg)
    }
}).catch(error => {
    console.log(error)
})

Parameter	Type	Description
chatRoomId	String	Chatroom ID
key	String	Chatroom attribute name. Key supports a combination of uppercase and lowercase letters, numbers, and special symbols + = - _, with a maximum length of 128 characters
isSendNotification	Boolean	Whether to send a notification message after successful deletion
notificationExtra	String	Additional information carried in the RC:chrmKVNotiMsg message

Batch Deletion

Call removeChatRoomEntries to batch delete chatroom attributes.

const chatRoomId = 'chatroom ID'
RongIMLib.removeChatRoomEntries(chatRoomId, {
    entries: ['']
}).then(res => {
    // Successfully deleted chatroom attributes
    if(res.code === 0){
        console.log(res.code)
    } else {
        console.log(res.code, res.msg)
    }
}).catch(error => {
    console.log(error)
})

Parameter	Type	Description
chatRoomId	String	Chatroom ID
options.entries	Array	A collection of chatroom attribute names. Key supports a combination of uppercase and lowercase letters, numbers, and special symbols + = - _, with a maximum length of 128 characters