please select
  • UIKit
  • SDK
  • Server APIs
Chat/
SDK/
Web/
Group/
SDK
  • Install Chat SDK
  • Initialize Chat SDK
  • Login and Logout
  • Client APIs
  • Changelog
  • Message
    • Overview
    • Send a Message
    • Receive a Message
    • Historical Message
    • Forward Messages
    • Modify a Message
    • Delete Messages
    • Clear History Message
    • Recall a Message
    • Send an Online Message
    • Message Read Receipt
    • Query Messages
    • Targeted Group Message
    • Do not Notify
    • Key-Value Extensions
    • Translation
  • Conversation
    • Overview
    • Conversation List
    • Get Conversations
    • Unread Count
    • Pin Conversations
    • Delete Conversations
    • Mark
    • Conversation Group
  • Group
    • Overview
    • Group Management
    • Group Profile
    • Group Member Management
    • Group Member Profile
    • Custom Group Attribute
    • Group Counter
  • Community Topic
    • Community Management
  • User Profile and Relationship Chain
    • User Profile
    • User Status
    • Friend Management
    • Friend Group
    • Block List
  • Guideline for Beginners
  • Console Guide
    • Creating and Upgrading an Application
    • Basic Configuration
    • Feature Configuration
    • Account Management
    • Group Management
    • Webhook Configuration
  • Product Introduction
    • Message Management
      • One-to-One Message
      • Message Storage
      • Offline Push
      • Group Message
      • Message Formats
    • Account System
      • Login Authentication
      • Online Status Management
    • Group Related
      • Group System
      • Group Management
    • User Profile and Relationship Chain
      • Profile Management
      • Relationship Chain Management
  • Purchase Guide
    • Billing Overview
    • Pricing
  • Error Codes
Docs Overview/
Chat/
SDK/
Web/
Group/
Custom Group Attribute/

Custom Group Attribute

Feature Description

With group attributes, you can manage the seats of audio chat rooms. When a user mics on, you can set a group attribute to manage the information of the user. When the user mics off, you can delete the group attribute. Other members can get the list of group attributes to display the seat list.

The group attribute feature has the following characteristics:
1. You can configure up to 16 group attributes. The size of each group attribute can be up to 4 KB, and the total size of all group attributes can be up to 16 KB.
2. The initGroupAttributes, setGroupAttributes, and deleteGroupAttributes APIs together can be called by a logged-in user up to ten times every five seconds in the SDK, and the 2996 error code will be called back if the limit is exceeded.
3. The getGroupAttributes API can be called by a logged-in user 20 times every five seconds in the SDK, and the 2996 error code will be called back if the limit is exceeded.
4. When you modify group attributes for the first time after each successful login, call getGroupAttributes to pull the latest group attributes before you initiate the modification operation again.
5. When multiple users modify the same group attributes at the same time, only the first user can execute successfully, and other users will receive the 10056 error code. After receiving this error code, please call getGroupAttributes to update the locally stored group attributes to the latest before you initiate the modification operation.
6. Before you use this feature in an audio-video group (AVChatRoom) after successful login, you need to call the joinGroup API to join the audio-video group. For a public group (Public), meeting group (Meeting), work group (Work), and community group (Community), you do not need to join the group again.

Initializing group attributes

API
chat.initGroupAttributes(options);
Parameters
The options parameter is of the Object type. It contains the following attribute values:
Name
Type
Description
groupID
String
Group ID
groupAttributes
Object
Group attributes
Return values
Promise
Sample
let promise = chat.initGroupAttributes({
  groupID: 'group1',
  groupAttributes: { key1: 'value1', key2: 'value2' }
});
promise.then(function(imResponse) {
  console.log(imResponse.data.groupAttributes); // Group attributes initialized successfully
}).catch(function(imError) {
  console.warn('initGroupAttributes error:', imError); // Error information
});

Setting group attributes

API
chat.setGroupAttributes(options);
Parameters
The options parameter is of the Object type. It contains the following attribute values:
Name
Type
Description
groupID
String
Group ID
groupAttributes
Object
Group attributes
Return values
Promise
Sample
let promise = chat.setGroupAttributes({
  groupID: 'group1',
  groupAttributes: { key1: 'value1', key2: 'value2' }
});
promise.then(function(imResponse) { // Set successfully
  console.log(imResponse.data.groupAttributes); // Group attributes set successfully
}).catch(function(imError) { // Setting failed
  console.warn('setGroupAttributes error:', imError); // Error information
});

Deleting group attributes

Note
1. To delete specified group attributes (key-value pairs), pass in a non-empty array for keyList. To delete all group attributes, pass in an empty array for keyList.
API
chat.deleteGroupAttributes(options);
Parameters
The options parameter is of the Object type. It contains the following attribute values:
Name
Type
Description
groupID
String
Group ID
keyList
Array
List of keys of the group attributes
Return values
Promise
Sample
// Delete the `key-value` of the specified group attributes
let promise = chat.deleteGroupAttributes({
  groupID: 'group1',
  keyList: ['key1', 'key2']
});
promise.then(function(imResponse) {
  console.log(imResponse.data.keyList); // List of group attributes deleted successfully
}).catch(function(imError) {
  console.warn('deleteGroupAttributes error:', imError); // Error information
});
// Delete all group attributes
let promise = chat.deleteGroupAttributes({
  groupID: 'group1',
  keyList: []
});
promise.then(function(imResponse) {
  console.log(imResponse.data.keyList); // List of group attributes deleted successfully
}).catch(function(imError) {
  console.warn('deleteGroupAttributes error:', imError); // Error information
});

Getting group attributes

Note
1. To get specified group attributes, pass in a non-empty array for keyList. To get all group attributes, pass in an empty array for keyList.
API
chat.getGroupAttributes(options);
Parameters
The options parameter is of the Object type. It contains the following attribute values:
Name
Type
Description
groupID
String
Group ID
keyList
Array
List of keys of the group attributes
Return values
Promise
Sample
// Get specified group attributes
let promise = chat.getGroupAttributes({
  groupID: 'group1',
  keyList: ['key1', 'key2']
});
promise.then(function(imResponse) { // Got successfully
  console.log(imResponse.data.groupAttributes); // Specified group attributes
}).catch(function(imError) { // Getting failed
  console.warn('getGroupAttributes error:', imError); // Error information
});
// Get all group attributes
let promise = chat.getGroupAttributes({
  groupID: 'group1',
  keyList: []
});
promise.then(function(imResponse) { // Got successfully
  console.log(imResponse.data.groupAttributes); // All group attributes
}).catch(function(imError) { // Getting failed
  console.warn('getGroupAttributes error:', imError); // Error information
});

Listening for a group attribute update event

let onGroupAttributesUpdated = function(event) {
   const groupID = event.data.groupID // Group ID
   const groupAttributes = event.data.groupAttributes //Updated group properties
   console.log(event.data);
};
chat.on(TencentCloudChat.EVENT.GROUP_ATTRIBUTES_UPDATED, onGroupAttributesUpdated);