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; or in card games like Werewolf, it can record the roles of users and the state of the game.
Functional Limitations
tip
- When a chatroom is destroyed, the custom attributes within it are also destroyed.
- Each chatroom allows a maximum of 100 attribute entries, stored in
Key-Valuepairs. - The client SDK does not limit the frequency of KV operations in chatrooms. It is recommended to keep the frequency of
Key-Valueoperations in each chatroom to 100 times or fewer per second (one operation on 100 KVs in one second is equivalent to 100 operations).
Enabling the Service
To use the Chatroom Attribute (KV) interface, the Chatroom Custom Attributes service must be enabled. You can enable this service on the Basic Features page in the Console.
If a server-side 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-side documentation Chatroom Attribute Synchronization (KV).
Adding a Chatroom KV
Method
Future<int> addChatRoomEntry(String targetId, String key, String value, bool deleteWhenLeft, bool overwrite, {IRCIMIWAddChatRoomEntryCallback? callback});
Parameter Description
| Parameter Name | Parameter Type | Description |
|---|---|---|
| targetId | String | The chatroom conversation ID |
| key | String | The name of the chatroom attribute. The Key supports a combination of uppercase and lowercase letters, numbers, and some 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 |
| deleteWhenLeft | bool | Whether to automatically delete the Key and Value when the user goes offline or exits |
| overwrite | bool | Whether to overwrite if the current key exists |
| callback | IRCIMIWAddChatRoomEntryCallback | Event callback. The SDK supports callback-based responses starting from version 5.3.1. Other callback methods for this interface are deprecated as of version 5.4.0. If the callback parameter is provided, only the callback will be triggered. |
Return Value
| Return Value | Description |
|---|---|
| Future<int> | The status code of the current interface operation. 0 indicates a successful call. The specific result needs to be implemented through the interface callback. Non-zero values indicate that the current interface call failed and will not trigger the interface callback. Refer to the error codes for detailed errors. |
Code Example
IRCIMIWAddChatRoomEntryCallback? callback = IRCIMIWAddChatRoomEntryCallback(onChatRoomEntryAdded: (int? code) {
//...
});
int? ret = await engine?.addChatRoomEntry(targetId, key, value, deleteWhenLeft, overwrite, callback:callback);
Callback Method
- onChatRoomEntryAdded
Function(int? code, String? targetId, String? key)? onChatRoomEntryAdded;
Parameter Description
| Parameter Name | Parameter Type | Description |
|---|---|---|
| code | int | The status code of the interface callback. 0 indicates success, while non-zero values indicate exceptions |
| targetId | String | The conversation ID |
| key | String | The name of the chatroom attribute |
Code Example
engine?.onChatRoomEntryAdded = (int? code, String? targetId, String? key) {
//...
};
Adding Multiple Chatroom KVs
Method
Future<int> addChatRoomEntries(String targetId, Map entries, bool deleteWhenLeft, bool overwrite, {IRCIMIWAddChatRoomEntriesCallback? callback});
Parameter Description
| Parameter Name | Parameter Type | Description |
|---|---|---|
| targetId | String | The chatroom conversation ID |
| entries | Map<String, String> | The chatroom attributes |
| deleteWhenLeft | bool | Whether to automatically delete the Key and Value when the user goes offline or exits |
| overwrite | bool | Whether to force overwrite |
| callback | IRCIMIWAddChatRoomEntriesCallback | Event callback. The SDK supports callback-based responses starting from version 5.3.1. Other callback methods for this interface are deprecated as of version 5.4.0. If the callback parameter is provided, only the callback will be triggered. |
Return Value
| Return Value | Description |
|---|---|
| Future<int> | The status code of the current interface operation. 0 indicates a successful call. The specific result needs to be implemented through the interface callback. Non-zero values indicate that the current interface call failed and will not trigger the interface callback. Refer to the error codes for detailed errors. |
Code Example
IRCIMIWAddChatRoomEntriesCallback? callback = IRCIMIWAddChatRoomEntriesCallback(onChatRoomEntriesAdded: (int? code, Map? errors) {
//...
});
int? ret = await engine?.addChatRoomEntries(targetId, entries, deleteWhenLeft, overwrite, callback:callback);
Callback Method
- onChatRoomEntriesAdded
Function(int? code, String? targetId, Map? entries, Map? errorEntries)? onChatRoomEntriesAdded;
Parameter Description
| Parameter Name | Parameter Type | Description |
|---|---|---|
| code | int | The status code of the interface callback. 0 indicates success, while non-zero values indicate exceptions |
| targetId | String | The conversation ID |
| entries | Map<String, String> | The chatroom attributes |
| errorEntries | Ma<String, int> | The attributes that encountered errors |
Code Example
engine?.onChatRoomEntriesAdded = (int? code, String? targetId, Map? entries, Map? errorEntries) {
//...
};
Loading a Chatroom KV
Method
Future<int> getChatRoomEntry(String targetId, String key, {IRCIMIWGetChatRoomEntryCallback? callback});
Parameter Description
| Parameter Name | Parameter Type | Description |
|---|---|---|
| targetId | String | The chatroom conversation ID |
| key | String | The key of the chatroom attribute |
| callback | IRCIMIWGetChatRoomEntryCallback | Event callback. The SDK supports callback-based responses starting from version 5.3.1. Other callback methods for this interface are deprecated as of version 5.4.0. If the callback parameter is provided, only the callback will be triggered. |
Return Value
| Return Value | Description |
|---|---|
| Future<int> | The status code of the current interface operation. 0 indicates a successful call. The specific result needs to be implemented through the interface callback. Non-zero values indicate that the current interface call failed and will not trigger the interface callback. Refer to the error codes for detailed errors. |
Code Example
IRCIMIWGetChatRoomEntryCallback? callback = IRCIMIWGetChatRoomEntryCallback(onSuccess: (Map? t) {
//...
}, onError: (int? code) {
//...
});
int? ret = await engine?.getChatRoomEntry(targetId, key, callback:callback);
Callback Method
- onChatRoomEntryLoaded
Function(int? code, String? targetId, Map? entry)? onChatRoomEntryLoaded;
Parameter Description
| Parameter Name | Parameter Type | Description |
|---|---|---|
| code | int | The status code of the interface callback. 0 indicates success, while non-zero values indicate exceptions |
| targetId | String | The conversation ID |
| entry | Map<String, String> | The retrieved attribute. |
Code Example
engine?.onChatRoomEntryLoaded = (int? code, String? targetId, Map? entry) {
//...
};
Loading All KVs for a Chatroom
Method
Future<int> getChatRoomAllEntries(String targetId, {IRCIMIWGetChatRoomAllEntriesCallback? callback});
Parameter Description
| Parameter Name | Parameter Type | Description |
|---|---|---|
| targetId | String | The chatroom conversation ID |
| callback | IRCIMIWGetChatRoomAllEntriesCallback | Event callback. The SDK supports callback-based responses starting from version 5.3.1. Other callback methods for this interface are deprecated as of version 5.4.0. If the callback parameter is provided, only the callback will be triggered. |
Return Value
| Return Value | Description |
|---|---|
| Future<int> | The status code of the current interface operation. 0 indicates a successful call. The specific result needs to be implemented through the interface callback. Non-zero values indicate that the current interface call failed and will not trigger the interface callback. Refer to the error codes for detailed errors. |
Code Example
IRCIMIWGetChatRoomAllEntriesCallback? callback = IRCIMIWGetChatRoomAllEntriesCallback(onSuccess: (Map? t) {
//...
}, onError: (int? code) {
//...
});
int? ret = await engine?.getChatRoomAllEntries(targetId, callback:callback);
Callback Method
- onChatRoomAllEntriesLoaded
Function(int? code, String? targetId, Map? entries)? onChatRoomAllEntriesLoaded;
Parameter Description
| Parameter Name | Parameter Type | Description |
|---|---|---|
| code | int | The status code of the interface callback. 0 indicates success, while non-zero values indicate exceptions |
| targetId | String | The conversation ID |
| entries | Map<String, String> | The retrieved collection of attributes. |
Code Example
engine?.onChatRoomAllEntriesLoaded = (int? code, String? targetId, Map? entries) {
//...
};
Removing a Chatroom KV
Method
Future<int> removeChatRoomEntry(String targetId, String key, bool force, {IRCIMIWRemoveChatRoomEntryCallback? callback});
Parameter Description
| Parameter Name | Parameter Type | Description |
|---|---|---|
| targetId | String | The chatroom conversation ID |
| key | String | The key of the chatroom attribute |
| force | bool | Whether to force deletion |
| callback | IRCIMIWRemoveChatRoomEntryCallback | Event callback. The SDK supports callback-based responses starting from version 5.3.1. Other callback methods for this interface are deprecated as of version 5.4.0. If the callback parameter is provided, only the callback will be triggered. |
Return Value
| Return Value | Description |
|---|---|
| Future<int> | The status code of the current interface operation. 0 indicates a successful call. The specific result needs to be implemented through the interface callback. Non-zero values indicate that the current interface call failed and will not trigger the interface callback. Refer to the error codes for detailed errors. |
Example Code
IRCIMIWRemoveChatRoomEntryCallback? callback = IRCIMIWRemoveChatRoomEntryCallback(onChatRoomEntryRemoved: (int? code) {
//...
});
int? ret = await engine?.removeChatRoomEntry(targetId, key, force, callback:callback);
Callback Method
- onChatRoomEntryRemoved
Function(int? code, String? targetId, String? key)? onChatRoomEntryRemoved;
Parameter Description
| Parameter Name | Parameter Type | Description |
|---|---|---|
| code | int | The status code of the interface callback. 0 indicates success, while non-zero values indicate exceptions |
| targetId | String | The conversation ID |
| key | String | The key of the chatroom attribute |
Code Example
engine?.onChatRoomEntryRemoved = (int? code, String? targetId, String? key) {
//...
};
Removing Multiple Chatroom KVs
Method
Future<int> removeChatRoomEntries(String targetId, List<String> keys, bool force, {IRCIMIWRemoveChatRoomEntriesCallback? callback});
Parameter Description
| Parameter Name | Parameter Type | Description |
|---|---|---|
| targetId | String | The chatroom conversation ID |
| keys | List<String> | The chatroom attributes |
| force | bool | Whether to force overwrite |
| callback | IRCIMIWRemoveChatRoomEntriesCallback | Event callback. The SDK supports callback-based responses starting from version 5.3.1. Other callback methods for this interface are deprecated as of version 5.4.0. If the callback parameter is provided, only the callback will be triggered. |
Return Value
| Return Value | Description |
|---|---|
| Future<int> | The status code of the current interface operation. 0 indicates a successful call. The specific result needs to be implemented through the interface callback. Non-zero values indicate that the current interface call failed and will not trigger the interface callback. Refer to the error codes for detailed errors. |
Code Example
IRCIMIWRemoveChatRoomEntriesCallback? callback = IRCIMIWRemoveChatRoomEntriesCallback(onChatRoomEntriesRemoved: (int? code) {
//...
});
int? ret = await engine?.removeChatRoomEntries(targetId, keys, force, callback:callback);
Callback Method
- onChatRoomEntriesRemoved
Function(int? code, String? targetId, List<String>? keys)? onChatRoomEntriesRemoved;
Parameter Description
| Parameter Name | Parameter Type | Description |
|---|---|---|
| code | int | The status code of the interface callback. 0 indicates success, while non-zero values indicate exceptions |
| targetId | String | The conversation ID |
| keys | List<String> | The collection of chatroom attribute keys |
Code Example
engine?.onChatRoomEntriesRemoved = (int? code, String? targetId, List<String>? keys) {
//...
};
Callback for KV Synchronization Completion When Joining a Chatroom
Method
Function(String? roomId)? onChatRoomEntriesSynced;
Parameter Description
| Parameter Name | Parameter Type | Description |
|---|---|---|
| roomId | String | The chatroom ID |
Code Example
engine?.onChatRoomEntriesSynced = (String? roomId) {
//...
};
Callback for Changes in Chatroom KVs
If KVs exist when joining a chatroom, this callback will return all KVs. Subsequent callbacks occur when others set or modify KVs.
Method
Function(RCIMIWChatRoomEntriesOperationType? operationType, String? roomId, Map? entries)? onChatRoomEntriesChanged;
Parameter Description
| Parameter Name | Parameter Type | Description |
|---|---|---|
| operationType | RCIMIWChatRoomEntriesOperationType | The type of operation |
| roomId | String | The chatroom ID |
| entries | Map<String, String> | The changed KVs |
Code Example
engine?.onChatRoomEntriesChanged = (RCIMIWChatRoomEntriesOperationType? operationType, String? roomId, Map? entries) {
//...
};