Skip to main content

Chatroom Custom Attributes Overview

The chatroom custom attributes (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 seat in the chatroom. In card game scenarios like Werewolf, it can be used to record user roles and game statuses. Clients can set up a chatroom attribute change listener to obtain real-time attribute changes.

Enable the Service​

Before using the chatroom custom attributes (KV) feature, please ensure that the service has been enabled for the current App Key. For details, see Enable Chatroom Custom Attributes. Once the service is enabled, both the client and server can set chatroom custom attributes (KV).

Service Limitations​

  • Each chatroom allows a maximum of 100 attribute entries, stored in Key-Value pairs.
  • When a chatroom is destroyed, its custom attributes are also destroyed.
  • Chatroom KV is also affected by the chatroom message discard policy. To ensure that attribute notification messages are not discarded, you can use the user allowlist service in the chatroom allowlist for protection. For details, see Enable Chatroom Allowlist Service.
  • Both client and server APIs can be used to manage chatroom attributes KV. Currently, the IM service does not impose a limit on the total operation frequency. To ensure the smooth operation of your app, it is recommended to maintain the total frequency of Key-Value operations in a single chatroom at 100 pairs per second or below (100 KV pairs in a single operation within one second).

Attribute Management Interfaces​

After enabling the service, you can use the following interfaces:

  • Set Chatroom Attribute: Set a custom attribute KV pair in a specified chatroom. This interface requires the user ID of the operator to be passed as the owner of the KV pair.
  • Batch Set Chatroom Attributes: Batch and forcibly set custom attribute KV pairs in a specified chatroom, with a maximum of 20 KV pairs per operation. If the attribute already exists, this interface will forcibly overwrite the owner user ID and value of the original KV pair.
  • Delete Chatroom Attribute: Delete a custom attribute KV pair in a specified chatroom. This interface requires the owner user ID of the KV pair to be passed.
  • Batch Delete Chatroom Attributes: Batch and forcibly delete custom attribute KV pairs in a specified chatroom, with a maximum of 20 KV pairs per operation. This interface will forcibly delete KV pairs without requiring the owner user ID of the KV pairs to be deleted. Admin users in the app can use this interface to clear business data in a specified chatroom.

Monitor Chatroom Custom Attribute Changes​

You can monitor chatroom attribute changes using the following methods:

  • Server Callback: You can configure a callback URL in the Console to receive chatroom attribute changes. The IM server will synchronize all chatroom attribute changes (such as setting, deleting, or deleting all operations) in your app to the specified address, allowing your app's backend to stay informed about chatroom attribute changes. For details, see Chatroom Attribute Synchronization (KV).
  • Client Callback: The client SDK provides a listener for chatroom attribute changes, which can monitor operations such as synchronization, setting, and deletion of chatroom attributes.
Last updated on