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 used to record the attributes of each microphone position in the chatroom. In card game scenarios like Werewolf, it can be used to record user roles and game statuses.

Limitations

tip

• Once a chatroom is destroyed, its custom attributes are also destroyed.
• Each chatroom can store up to 100 attributes in Key-Value pairs.
• The client SDK does not limit the frequency of KV operations in chatrooms. It is recommended to keep the frequency of Key-Value operations below 100 times per second per chatroom (one operation involving 100 KVs is equivalent to 100 operations).

Enabling the Service

To use the chatroom attribute (KV) interface, you need to enable the Chatroom Custom Attributes service. You can activate this service on the Basic Features page in the Console.

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

Adding Chatroom KV

Method

addChatRoomEntry(
  targetId: string, 
  key: string, 
  value: string, 
  deleteWhenLeft: boolean, 
  overwrite: boolean, 
  callback: IRCIMIWAddChatRoomEntryCallback
): Promise<number>;

Parameter Description

Parameter	Type	Description
targetId	string	The chatroom conversation ID
key	string	The chatroom attribute name. The key can include uppercase and lowercase letters, numbers, and special characters + = - _, with a maximum length of 128 characters
value	string	The value corresponding to the chatroom attribute, with a maximum length of 4096 characters
deleteWhenLeft	boolean	Whether to automatically delete the Key-Value pair when the user disconnects or leaves
overwrite	boolean	Whether to overwrite if the key already exists
callback	IRCIMIWAddChatRoomEntryCallback	Callback for the interface result.

Return Value

Return Value	Description
number	The status code of the current operation. 0 indicates success, and the specific result is returned via the callback. Non-zero values indicate failure, and no callback will be triggered. Refer to the error codes for details.

Code Example

const callback = {
    onChatRoomEntryAdded: (code: number) => {
        //...
    },
};
let code = await engine.addChatRoomEntry(targetId, key, value, deleteWhenLeft, overwrite, callback);

Adding Multiple Chatroom KVs

Method

addChatRoomEntries(
  targetId: string, 
  entries: Map<string, string>, 
  deleteWhenLeft: boolean, 
  overwrite: boolean, 
  callback: IRCIMIWAddChatRoomEntriesCallback
): Promise<number>;

Parameter Description

Parameter	Type	Description
targetId	string	The chatroom conversation ID
entries	Map<string, string>	The chatroom attributes
deleteWhenLeft	boolean	Whether to automatically delete the Key-Value pairs when the user disconnects or leaves
overwrite	boolean	Whether to force overwrite
callback	IRCIMIWAddChatRoomEntriesCallback	Callback for the interface result.

Return Value

Return Value	Description
number	The status code of the current operation. 0 indicates success, and the specific result is returned via the callback. Non-zero values indicate failure, and no callback will be triggered. Refer to the error codes for details.

Code Example

const callback = {
    onChatRoomEntriesAdded: (code: number, errors: Map<string, number>) => {
        //...
    },
};
let code = await engine.addChatRoomEntries(targetId, entries, deleteWhenLeft, overwrite, callback);

Loading Chatroom KV

Method

getChatRoomEntry(
  targetId: string, 
  key: string, 
  callback: IRCIMIWGetChatRoomEntryCallback
): Promise<number>;

Parameter Description

Parameter	Type	Description
targetId	string	The chatroom conversation ID
key	string	The chatroom attribute key
callback	IRCIMIWGetChatRoomEntryCallback	Callback for the interface result.

Return Value

Return Value	Description
number	The status code of the current operation. 0 indicates success, and the specific result is returned via the callback. Non-zero values indicate failure, and no callback will be triggered. Refer to the error codes for details.

Code Example

const callback = {
    onSuccess: (t: Map<string, string>) => {
        //...
    },
    onError: (code: number) => {
        //...
    },
};
let code = await engine.getChatRoomEntry(targetId, key, callback);

Loading All KVs in a Chatroom

Method

getChatRoomAllEntries(
  targetId: string, 
  callback: IRCIMIWGetChatRoomAllEntriesCallback
): Promise<number>;

Parameter Description

Parameter	Type	Description
targetId	string	The chatroom conversation ID
callback	IRCIMIWGetChatRoomAllEntriesCallback	Callback for the interface result.

Return Value

Return Value	Description
number	The status code of the current operation. 0 indicates success, and the specific result is returned via the callback. Non-zero values indicate failure, and no callback will be triggered. Refer to the error codes for details.

Code Example

const callback = {
    onSuccess: (t: Map<string, string>) => {
        //...
    },
    onError: (code: number) => {
        //...
    },
};
let code = await engine.getChatRoomAllEntries(targetId, callback);

Removing Chatroom KV

Method

removeChatRoomEntry(
  targetId: string, 
  key: string, 
  force: boolean, 
  callback: IRCIMIWRemoveChatRoomEntryCallback
): Promise<number>;

Parameter Description

Parameter	Type	Description
targetId	string	The chatroom conversation ID
key	string	The chatroom attribute key
force	boolean	Whether to force deletion
callback	IRCIMIWRemoveChatRoomEntryCallback	Callback for the interface result.

Return Value

Return Value	Description
number	The status code of the current operation. 0 indicates success, and the specific result is returned via the callback. Non-zero values indicate failure, and no callback will be triggered. Refer to the error codes for details.

Example Code

const callback = {
    onChatRoomEntryRemoved: (code: number) => {
        //...
    },
};
let code = await engine.removeChatRoomEntry(targetId, key, force, callback);

Removing Multiple Chatroom KVs

Method

removeChatRoomEntries(
  targetId: string, 
  keys: Array<string>, 
  force: boolean, 
  callback: IRCIMIWRemoveChatRoomEntriesCallback
): Promise<number>;

Parameter Description

Parameter	Type	Description
targetId	string	The chatroom conversation ID
keys	Array<string>	The chatroom attributes
force	boolean	Whether to force overwrite
callback	IRCIMIWRemoveChatRoomEntriesCallback	Callback for the interface result.

Return Value

Return Value	Description
number	The status code of the current operation. 0 indicates success, and the specific result is returned via the callback. Non-zero values indicate failure, and no callback will be triggered. Refer to the error codes for details.

Code Example

const callback = {
    onChatRoomEntriesRemoved: (code: number) => {
        //...
    },
};
let code = await engine.removeChatRoomEntries(targetId, keys, force, callback);

Callback When Chatroom KV Synchronization is Complete

This callback is triggered when KV synchronization is complete upon joining a chatroom.

Method

setOnChatRoomEntriesSyncedListener(listener?: (roomId: string) => void): void;

Parameter Description

Parameter	Type	Description
roomId	string	The chatroom ID

Code Example

engine?.setOnChatRoomEntriesSyncedListener((roomId: string) => {
    //...
});

Callback When Chatroom KV Changes

If KVs exist when joining a chatroom, this callback will return all KVs. Subsequent callbacks will be triggered when others set or modify KVs.

Method

setOnChatRoomEntriesChangedListener(listener?: (operationType: RCIMIWChatRoomEntriesOperationType, roomId: string, entries: Map<string, string>) => void): void;

Parameter Description

Parameter	Type	Description
operationType	RCIMIWChatRoomEntriesOperationType	The type of operation
roomId	string	The chatroom ID
entries	Map<string, string>	The changed KVs

Code Example

engine?.setOnChatRoomEntriesChangedListener(
    (operationType: RCIMIWChatRoomEntriesOperationType, roomId: string, entries: Map<string, string>) => {
        //...
    }
);