please select
Docs Overview/
Chat/
SDK/
Web/
Group/
Group Counter/

Group Counter

Description

Chat SDK provides the group counter feature, allowing a certain number of counters to be set for each group.
Unlike Group Custom Attributes, group counters are mainly used to store integer-type data. You can use group counters to store additional group-related information, such as the cumulative number of viewers, the number of views, the number of likes received by the host, and the total number of gifts given by the audience to the host in a live group.
Indication
1. Group counters support all types of groups, excluding topic-enabled community groups.
2. This feature is only supported in the Advanced Version, and requires purchasing the Premium Version.
Keep the following in mind for group counters:
1. A single group can support up to 20 group counters, meaning the number of keys in a single group should not exceed 20.
2. The key for a single group counter cannot exceed 128 characters, and the value must be an integer (up to 64-bit signed integers).
3. setGroupCounters, increaseGroupCounter, and decreaseGroupCounter APIs combine computations, with an SDK limit of 20 calls per 5 seconds per log in to user. If exceeded, the interface returns error code 2996.
4. getGroupCounters interface calculates independently. The SDK limits a single user to a maximum of 20 calls within 5 seconds per log in. If the limit is exceeded, the interface returns error code 2996.

Display Effect





Setting Group Counters

You can call the setGroupCounters interface to set multiple group counters. After the counter is successfully set, the TencentCloudChat.EVENT.GROUP_COUNTER_UPDATED event is triggered. Refer to the usage of TencentCloudChat.EVENT.GROUP_COUNTER_UPDATED in the Group Counter Change Notification section below.
Indication
1. If the key of the counter you are about to set exists, then the value of the counter will be updated directly; if not, then a new key-value will be added.
2. If multiple users set the same counter at the same time, the final value of the counter will be used. It's recommended that the group owner performs counter setting operations.
API
chat.setGroupCounters(options);
Parameters
The options parameter is of the Object type, and contains the following attribute values:
Name
Type
Description
groupID
String
Group ID
counters
Object
Group Counter key-value
Return values
Promise
Example
// Set the values of counters key1 and key2 to 0
let promise = chat.setGroupCounters({
  groupID: 'group1',
  counters: { key1: 0, key2: 0 }
});
promise.then(function(imResponse) { // Set successfully
  console.log(imResponse.data.counters); // Group counters set successfully
}).catch(function(imError) { // Setting failed
  console.warn('setGroupCounters error:', imError); // Error information
});

Incrementing the Value of a Group Counter

You can call the incremental interface increaseGroupCounter to perform the accumulation operation on the group counter. Upon successful operation, the TencentCloudChat.EVENT.GROUP_COUNTER_UPDATED event will be triggered. See the section Group Counter Change Notification below for the usage of TencentCloudChat.EVENT.GROUP_COUNTER_UPDATED.
Indication
1. The value parameter in the interface represents the change amount; calling the interface will accumulate the passed change amount on top of the current value;
2. If the key of the counter you are about to set already exists, then it directly performs an increment operation based on the passed value on top of the current value; otherwise, add the key, and perform an increment operation based on the passed value starting from a default value of 0.
API
chat.increaseGroupCounter(options);
Parameters
The options parameter is of the Object type, and contains the following attribute values:
Name
Type
Description
groupID
String
Group ID
key
String
Group Counter Key
value
Number
Incremental Change Amount of the Group Counter Key
Return values
Promise
Example
// Assuming the current value of counter key1 is 8. After calling the increaseGroupCounter interface and passing the incremental change amount value of 2, the final value of key1 becomes 10.
let promise = chat.increaseGroupCounter({
  groupID: 'group1',
  key: 'key1',
  value: 2,
});
promise.then(function(imResponse) { // Increment successful
  console.log(imResponse.data);
  const { groupID, key, value } = imResponse.data;
}).catch(function(imError) { // Increment failed
  console.warn('increaseGroupCounter error:', imError);
});

Decrementing the Value of a Group Counter

You can call the decrement interface decreaseGroupCounter to perform a decrement operation on the group counter. After a successful operation, the TencentCloudChat.EVENT.GROUP_COUNTER_UPDATED event will be triggered. Refer to the usage of TencentCloudChat.EVENT.GROUP_COUNTER_UPDATED in the Group Counter Change Notification section below.
Indication
1. The 'value' parameter in the API represents the decrement amount. After calling the API, the current value will be reduced by the specified decrement amount;
2. If the key of the counter you are about to set already exists, then it directly performs a decrement operation based on the passed value on top of the current value; otherwise, add the key, and perform a decrement operation based on the passed value starting from a default value of 0.
API
chat.decreaseGroupCounter(options);
Parameters
The options parameter is of the Object type, and contains the following attribute values:
Name
Type
Description
groupID
String
Group ID
key
String
Group Counter Key
value
Number
Incremental Change Amount of the Group Counter Key
Return values
Promise
Example
// Assuming the current value of the counter key1 is 8.
// After calling the decreaseGroupCounter API with a decrement value of 2
// The final value of key1 becomes 6.
let promise = chat.decreaseGroupCounter({
  groupID: 'group1',
  key: 'key1',
  value: 2
});
promise.then(function(imResponse) { // Decrement successful
  console.log(imResponse.data);
  const { groupID, key, value } = imResponse.data;
}).catch(function(imError) { // Setting failed
  console.warn('decreaseGroupCounter error:', imError);
});

Getting Group Counters

You can call the getGroupCounters API to pass in a set of specified keys to get the corresponding group counter information. The API will return all key-value pairs matching the keys passed in.
Indication
If no keyList is passed, all group counters are returned.
API
chat.getGroupCounter(options);
Parameters
The options parameter is of the Object type, and contains the following attribute values:
Name
Type
Description
groupID
String
Group ID
keyList
Array | undefined
List of keys of the group counters
Return values
Promise
Example
// Get values of group counters key1 and key2
let promise = chat.getGroupCounters({
  groupID: 'group1',
  keyList: ['key1', 'key2']
});
promise.then(function(imResponse) { // Got successfully
  console.log(imResponse.data.counters);
}).catch(function(imError) {
  console.warn('getGroupCounters error:', imError); // Error information
});
// Get all counters of a group
let promise = chat.getGroupCounters({
  groupID: 'group1'
});
promise.then(function(imResponse) { // Got successfully
  console.log(imResponse.data.counters);
}).catch(function(imError) {
  console.warn('getGroupCounters error:', imError); // Error information
});

Group Counter Change Notification

When you call the setGroupCounters, increaseGroupCounter, or decreaseGroupCounter interfaces to modify the group counters, the TencentCloudChat.EVENT.GROUP_COUNTER_UPDATED event will be triggered and the updated value will be returned.
Indication
1. Before using the above events, you need to call the on interface to register the group counter change event.
Example
let onGroupCounterUpdated = function(event) {
  const { groupID, key, value } = event.data;
  // groupID - Group ID
  // key - Group counter key
  // value - Value corresponding to the group counter key
};
chat.on(TencentCloudChat.EVENT.GROUP_COUNTER_UPDATED, onGroupCounterUpdated);