Chatroom Attribute Management (KV)

The Chatroom Attributes (KV) Management Interface is used to set custom attributes in specified chatrooms.

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

Feature Limitations

tip

• When a chatroom is destroyed, all its custom attributes are also destroyed.
• Each chatroom allows a maximum of 100 attribute entries stored in Key-Value pairs.
• The client SDK imposes no rate limits on KV operations. It is recommended to keep the operation frequency below 100 times per second per chatroom (a single operation involving 100 KVs counts as 100 operations).

Enabling the Service

Using the Chatroom Attributes (KV) interface requires the Chatroom Custom Attributes feature (enabled by default).

If a server callback URL is configured, the RC server will synchronize chatroom attribute changes (set, delete, bulk delete, etc.) to the specified callback address. See server documentation Chatroom Attribute Synchronization (KV).

Setting Up Chatroom KV Listener

Call the addEventListener method to set up a chatroom KV listener.

tip

• The event listener should be registered globally and only once to avoid duplicate event notifications.
• The event callback data type is IChatroomListenerData

Sample Code

const listener = (event) => {
  if (event.rejoinedRoom) {
    console.log('SDK internal chatroom reconnection 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)

Get Single Attribute

Call the getChatRoomEntry method to retrieve a single attribute.

Interface

RongIMLib.getChatRoomEntry(chatRoomId, key)

Parameters

Parameter	Type	Required	Description
chatRoomId	string	Yes	Chatroom ID
key	string	Yes	Chatroom attribute name. Keys support uppercase/lowercase letters, numbers, and special characters + = - _ with maximum length of 128 characters

Sample Code

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

RongIMLib.getChatRoomEntry(chatRoomId, key).then(res => {
    // Successfully retrieved 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)
})

Get All Attributes

Call the getAllChatRoomEntries method to retrieve all attributes.

Interface

RongIMLib.getAllChatRoomEntries(chatRoomId)

Parameters

Parameter	Type	Required	Description
chatRoomId	string	Yes	Chatroom ID

Sample Code

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)
})

Set Single Attribute

Call the setChatRoomEntry method to set an attribute.

Interface

RongIMLib.setChatRoomEntry(chatRoomId, entry)

Parameters

Parameter	Type	Required	Description
chatRoomId	string	Yes	Chatroom ID
entry	IChatroomEntry	Yes	Chatroom attribute configuration parameters

Sample Code

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

Force Set Single Attribute

Forcefully sets a single chatroom attribute, allowing modification of attributes created by others. Call forceSetChatRoomEntry to force-set chatroom attributes. Stored as key = value. When the key doesn't exist, it adds the attribute; when the key exists, it updates the value. Force setting allows modifying attributes created by others.

Interface

RongIMLib.forceSetChatRoomEntry(chatRoomId, entry)

Parameters

Parameter	Type	Required	Description
chatRoomId	string	Yes	Chatroom ID
entry	IChatroomEntry	Yes	Chatroom attribute configuration parameters

Sample Code

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

Batch Set Attributes

Call the setChatRoomEntries method to batch set chatroom attributes.

Interface

RongIMLib.setChatRoomEntries(chatRoomId, options)

Parameters

Parameter	Type	Required	Description
chatRoomId	string	Yes	Chatroom ID
options	IChatroomEntries	Yes	Chatroom attribute configuration parameters

tip

Starting from SDK v5.3.4, this interface supports force-setting multiple attributes via the options.isForce property, which can directly overwrite attributes created by others.

Sample Code

const entries = [{key: '',value: ''}]
const options = {
    entries,
    isAutoDelete:true, // Whether to clear this attribute when user exits 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)
})

Delete Single Attribute

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

Interface

RongIMLib.removeChatRoomEntry(chatRoomId, entry)

Parameters

Parameter	Type	Required	Description
chatRoomId	string	Yes	Chatroom ID
entry	IRemoveChatroomEntry	Yes	Chatroom attribute

Sample Code

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

Call the forceRemoveChatRoomEntry method to forcibly delete chatroom custom attributes. This allows deletion of attributes created by others.

Interface

RongIMLib.forceRemoveChatRoomEntry(chatRoomId, entry)

Parameter Description

Parameter	Type	Required	Description
chatRoomId	string	Yes	Chatroom ID
entry	IRemoveChatroomEntry	Yes	Chatroom attribute deletion configuration parameters

Example Code

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

Batch Deletion

Call the removeChatRoomEntries method to batch delete chatroom attributes.

Interface

RongIMLib.removeChatRoomEntries(chatRoomId, options);

Parameter Description

Parameter	Type	Required	Description
chatRoomId	string	Yes	Chatroom ID
options	object	Yes	Chatroom attribute deletion configuration parameters

• options Parameter Description

Parameter	Type	Required	Description
entries	string[]	Yes	Collection of chatroom attribute names. Keys support combinations of uppercase/lowercase English letters, numbers, and special symbols + = - _, with a maximum length of 128 characters
notificationExtra	string	No	Custom notification field

Example Code

const chatRoomId = 'chatroomID'
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)
})