Group Members

Update time: 2023/03/24 02:49:55

NIM SDK can query users, add or remove group members, and manage roles. All members are categorized into group owners, administrators, and regular members by permission.

How it works

C++

The nim::Team class provides methods used to manage group members with member privilege management.

A group can have members of three roles, group owner (kNIMTeamUserTypeCreator ), administrator (kNIMTeamUserTypeManager ) and regular member (kNIMTeamUserTypeNomal ). For more information, see NIMTeamUserType.

  • The group owner is the group creator by default, and can be transferred by calling the TransferTeamAsync method.
  • Administrators are assigned by the group owner, and the group owner add administrators using AddManagersAsync.
  • After a user join the group, the user becomes regular member by default. The user can request other roles from the group owner.
  • NIMTeamUserTypealso contains the kNIMTeamUserTypeApply and kNIMTeamUserTypeLocalWaitAccept types indicating the users that has sent join requests for approval.
C

The nim_team header file defines functions used to manage group members with member privilege management.

A group can have members of three roles, group owner (kNIMTeamUserTypeCreator), administrator (kNIMTeamUserTypeManager) and regular member (kNIMTeamUserTypeNomal).

  • The group owner is the group creator by default, and can be transferred by calling the nim_team_transfer_team_async function.
  • Administrators are assigned by the group owner, and the group owner add administrators using nim_team_add_managers_async.
  • After a user join the group, the user becomes regular member by default. The user can request other roles from the group owner.
  • NIMTeamUserTypealso contains the kNIMTeamUserTypeApply and kNIMTeamUserTypeLocalWaitAccept types indicating the users that has sent join requests for approval.

Prerequisites

  • The group is created and the user is in the group. For more information, see Manage groups
  • Listeners for group events are registered. For more information, see [Listeners for group events](https://doc.yunxin.163.com/messaging/docs/Tc4NzcyNDg?platform=pc#Listeners for group events).

Manage administrators

Add administrators

If a member leaves a group. all group members will receive a notification of kNIMMessageTypeNotification and the trigger event is kNIMNotificationIdTeamAddManager.

Only the group owner have the permission to add administrators.

C++

Add an administrator by calling the AddManagersAsync method.

Parameters:

Parameter Description
tid Group ID
ids Accounts to be assigned administrator.
json_extension Custom extension field.
cb Callback for adding an administrator.

Sample code:

void OnTeamEventCallback(const nim::TeamEvent& result)
{
	···
}

foo()
{
	std::list<std::string> uids_list;
	uids_list.push_back("user_id");
	nim::Team::AddManagersAsync("tid_", uids_list, &OnTeamEventCallback);
}

Error codes

Code Description
200 The operation was successful.
802 No permissions
803 Group does not exist
805 Invalid group type
C

Add an administrator by calling the nim_team_add_managers_async function.

Sample code:

void CallbackTeamOperate(int error, int team_operate, const char *tid, const char* str, const char *json_exten, const void *user_data)
{
	if (error == kNIMResSuccess)
	{
		...
	}
	else
	{
		...
	}
}

typedef void(*nim_team_add_managers_async)(const char *tid, const char *jsonlist_admin_ids, const char *json_extension, nim_team_event_cb_func cb, const void* user_data);

void foo()
{
	Json::Value values;
	values.append("user_id");

	nim_team_add_managers_async func = (nim_team_add_managers_async) GetProcAddress(hInst, "nim_team_add_managers_async");
	func("tid", values.toStyledString().c_str(), nullptr, &CallbackTeamOperate, nullptr);
}

Remove an administrator

If a member leaves a group. all group members will receive a notification of kNIMMessageTypeNotification and the trigger event is kNIMNotificationIdTeamRemoveManager.

Only the group owner has the permission to remove administrators.

C++

Remove an administrator by calling the RemoveManagersAsync method.

Parameters:

Parameter Description
tid Group ID
ids Accounts to be unassigned administrator.
json_extension Custom extension field.
cb Callback for removing an administrator.

Sample code:

void OnTeamEventCallback(const nim::TeamEvent& result)
{
	···
}

foo()
{
	std::list<std::string> uids_list;
	uids_list.push_back("user_id");
	nim::Team::RemoveManagersAsync("tid_", uids_list, &OnTeamEventCallback);
}

Error codes

Code Description
200 The operation was successful.
802 No permissions
803 Group does not exist
805 Invalid group type
C

Remove an administrator by calling the nim_team_remove_managers_async function.

Sample code:

void CallbackTeamOperate(int error, int team_operate, const char *tid, const char* str, const char *json_exten, const void *user_data)
{
	if (error == kNIMResSuccess)
	{
		...
	}
	else
	{
		...
	}
}

typedef void(*nim_team_remove_managers_async)(const char *tid, const char *jsonlist_admin_ids, const char *json_extension, nim_team_event_cb_func cb, const void* user_data);

void foo()
{
	Json::Value values;
	values.append("user_id");

	nim_team_remove_managers_async func = (nim_team_remove_managers_async) GetProcAddress(hInst, "nim_team_remove_managers_async");
	func("tid", values.toStyledString().c_str(), nullptr, &CallbackTeamOperate, nullptr);
}

Edit the member profile

Edit the nickname of a group member

If the group owner or an administrator edits the nickname of a group member, all group members will receive a notification of kNIMMessageTypeNotification and the trigger event is kNIMNotificationIdTeamSyncUpdateMemberProperty.

Only the group owner has the permission to edit the nickname of a group member.

C++

Edit the nickname of a group member by calling the UpdateOtherNickAsync method.

Parameters:

Parameter Description
prop Member attribute. For more information, see TeamMemberProperty
json_extension Custom extension field.
cb Callback for edit the member profile.

Sample code:

TeamMemberProperty property;
property.member_info_json_value_ = params;
Team::UpdateOtherNickAsync(property, [this](const TeamEvent& team_event) {
	// process team event
});

Error codes

Code Description
200 The operation was successful.
802 No permissions
803 Group does not exist
804 The user is not a member of a group.
805 Invalid group type
C

Edit the nickname of a group member by calling the nim_team_update_other_nick_async function.

Sample code:

static void CallbackFunc(int res_code,
    int notification_id,
    const char* tid,
    const char* result,
    const char* json_extension,
    const void* user_data) {
    // process result
}
const char* team_member_json;
// ...
nim_team_update_other_nick_async(team_member_json, "", &CallbackFunc, NULL);

Edit the personal profile of the current user in a group

If the current user edits the personal profile, all group members will receive a notification of kNIMMessageTypeNotification and the trigger event is kNIMNotificationIdTeamSyncUpdateMemberProperty.

C++

Edit the personal profile of the current user in a group by calling the UpdateMyPropertyAsync method.

Parameters:

Parameter Description
prop Member attribute. For more information, see TeamMemberProperty
json_extension Custom extension field.
cb Callback for edit the member profile.

Sample code:

TeamMemberProperty property;
property.member_info_json_value_ = params;
Team::UpdateMyPropertyAsync(property, [this](const TeamEvent& team_event) {
	// process team event
});

Error codes

Code Description
200 The operation was successful.
803 Group does not exist
804 The user is not a member of a group.
805 Invalid group type
C

Edit the personal profile of the current user in a group by calling the nim_team_update_my_property_async function.

Sample code:

static void CallbackFunc(int res_code,
    int notification_id,
    const char* tid,
    const char* result,
    const char* json_extension,
    const void* user_data) {
    // process result
}
const char* team_member_json;
// ...
nim_team_update_my_property_async(team_member_json, "", &CallbackFunc, NULL);

Mute members

Mute all group members

Only the group owner has the permission to mute or unmute all members.

Two type of mute methods are available for muting all members.

  • If the mute type NIMTeamMuteType is set to kNIMTeamMuteTypeAllMute, all members, including the group owner and administrators, are muted.
  • If the value of NIMTeamMuteType is set to kNIMTeamMuteTypeNomalMute , only regular members, not the group owner and administrators, are muted.
C++

Mute or unmute all members by calling the MuteAsync method.

Parameters:

Parameter Description
tid Group ID
set_mute Determine whether to mute all group members.
true: mute all group members.
false: unmute all group members.
json_extension Custom extension field.
cb Callback for muting all group members.

Sample code:

Team::MuteAsync("tid", true, [this](const TeamEvent& team_event) {
	// process team event
});

Error codes

Code Description
200 The operation was successful.
414 Invalid parameters
C

Mute or unmute all members by calling the nim_team_mute_async function.

Sample code:

static void CallbackFunc(int res_code,
    int notification_id,
    const char* tid,
    const char* result,
    const char* json_extension,
    const void* user_data) {
    // process result
}
nim_team_mute_async("tid", true, "", &CallbackFunc, NULL);

Mute a specified member

If a member is muted, all group members will receive a notification of kNIMMessageTypeNotification and the trigger event is kNIMNotificationIdTeamMuteMember.

Only the group owner can mute a specified member.

C++

Mute a specified member by calling the MuteMemberAsync method.

Parameters:

Parameter Description
tid Group ID
Member_id The member to be muted.
set_mute Whether to mute the member.
true: mute all group members.
false: unmute all group members.
json_extension Custom extension field.
cb Callback for muting all group members.

Sample code:

void CallbackMuteMember(const TeamEvent& team_event)
{
	// Custom implementation
	char log[128];
	sprintf_s(log, "id: %s, rescode: %d, tid: %s", GetTeamEventCommandText((nim::NIMNotificationId)team_event.notification_id_).c_str(), team_event.res_code_, team_event.team_id_.c_str());
	MessageBoxA(nullptr, log, "team_event", 0);
}

void foo(const std::string& team_id, const std::string& account_id, bool mute)
{
	Team::MuteMemberAsync(team_id, account_id, bool, &CallbackMuteMember);
}

Error codes

Code Description
200 The operation was successful.
414 Invalid parameters
404 The target member does not exist.
803 Group does not exist.
802 No permissions
C

Mute a specified member by calling the nim_team_mute_member_async function.

Sample code:

nim_team_mute_member_async(const char *tid, const char *member_id, bool set_mute, const char *json_extension, nim_team_opt_cb_func cb, const void *user_data);

The result returned by the callback nim_team_opt_cb_func:

//nim_cpp_team.cpp
static void CallbackTeamChange(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
	if (user_data)
	{
		Team::TeamEventCallback* cb_pointer = (Team::TeamEventCallback*)user_data;
		if (*cb_pointer)
		{
			TeamEvent team_event;
			ParseTeamEvent(res_code, PCharToString(tid), (nim::NIMNotificationId)notification_id, PCharToString(result), team_event);
			(*cb_pointer)(team_event);
		}
		delete cb_pointer;
	}
}

Query group members

Query operations may read cached data from the local database or synchronize data from the server. Therefore, such operations may take a long time.

Query the information about group members

C++

Query the information about group members by calling the QueryTeamMembersAsync method.

Parameters:

Parameter Description
tid Group ID
json_extension Custom extension field.
cb Callback for querying group members.

Sample code:

void OnGetTeamMembers(const std::string& team_id, int count, const std::list<nim::TeamMemberProperty>& team_member_list)
{
	for (const auto& member : team_member_list)
	{
		···
	}
}

foo()
{
	nim::Team::QueryTeamMembersAsync("tid_", &OnGetTeamMembers);
}

Error codes

Code Description
200 The operation was successful.
406 No data change
802 No permissions
C

Query the information about group members by calling the nim_team_query_team_members_async function.

You can specify parameters to query details and whether invalid members are included.

Sample code:

void CallbackQueryTeamMembersCb(const char * tid, int count, bool include_user_info, const char* str, const char *json_exten, const void *user_data)
{
	//Parse string
}

typedef void(*nim_team_query_team_members_async)(const char *tid, bool include_user_info, const char *json_extension, nim_team_query_team_members_cb_func cb, const void* user_data);

void foo()
{
	nim_team_query_team_members_async func = (nim_team_query_team_members_async) GetProcAddress(hInst, "nim_team_query_team_members_async");
	func("tid", include_user_info ? true : false, nullptr, &CallbackQueryTeamMembersCb, nullptr);
}

:::

Query a specified member

C++

Query the information about a specified member by group ID and account by calling the QueryTeamMemberAsync method or synchronous calling the QueryTeamMemberBlock method.

Parameters:

Parameter Description
tid Group ID
id Member ID
json_extension Custom extension field.
cb Callback for querying group members.

Sample code:

// asynchronous call
void OnQueryMyTeamMemberInfo(const std::string& tid, const nim::TeamMemberProperty& team_member_info)
{
	...
}

foo()
{
	nim::Team::QueryTeamMemberAsync("tid_","accid_", OnQueryMyTeamMemberInfo);
}

C

Query the information about a specified member by group ID and account by calling the nim_team_query_team_member_async function or synchronous calling the nim_team_query_team_member_block function.

Sample code:

// asynchronous call
void CallbackQueryTeamMember(const char *tid, const char *accid, const char *result, const char *json_extension, const void *user_data)
{
	// Parse the result
}

typedef void(*nim_team_query_team_member_async)(const char *tid, 	const char *accid, const char *json_extension, nim_team_query_team_member_cb_func cb, const void *user_data);

void foo()
{
	nim_team_query_team_member_async func = (nim_team_query_team_member_async) GetProcAddress(hInst, "nim_team_query_team_member_async");
	func("tid", "accid", nullptr, &CallbackQueryTeamMember, nullptr);
}

Query the information about the current user in all joined groups

C++

Query the information about the current user in all joined groups by calling the QueryMyAllMemberInfosAsync method.

Parameters:

Parameter Description
json_extension Custom extension field.
cb Callback for querying group members.

Sample code:

Team::QueryMyAllMemberInfosAsync([this](int count, const std::list<TeamMemberProperty>& props) {
	// process props
});
C

Query the information about the current user in all joined groups by calling the nim_team_query_my_all_member_infos_async function.

Sample code:

static void CallbackFunc(int count, const char* result, const char* json_extension, const void* user_data) {
    // process result
}
nim_team_query_my_all_member_infos_async("", &CallbackFunc, NULL);

After retrieving the list of all groups you have joined, you can use the bits field in the member information to determine whether a notification is sent when a group receives a message.

Query the inviter of a group member

If the value is empty, the member joined the group without invitation.

C++

Query the inviter of a group member by calling the QueryTeamMembersInvitor method.

Parameters:

Parameter Description
tid Group ID
Members The list of members whose inviters are queried, up to 200 members are queried at a time
If the number of group members is less than or equal to 200, it is an optional parameter. If unspecified, all members are queried by default. If the number of group members is greater than 200, multiple calls are required to get the inviters of all group members.
cb Callback for querying group members.

Sample code:

Team::QueryTeamMembersInvitor("tid", {"member1", "member2"},
		[this](NIMResCode res_code, const std::string& tid, const std::map<std::string, std::string>& invitor_map) {
			// process result
		});
C

Query the inviter of a group member by calling the nim_team_query_members_invitor function.

Sample code:

static void CallbackFunc(int res_code, const char* tid, const char* result, const void* user_data) {
    // process result
}
nim_team_query_members_invitor("tid", "[\"member1\", \"member2\"]", &,NULL)

Query muted members in a group

C++

Query muted members in a group by calling the QueryMuteListOnlineAsync method.

Sample code:

void CallbackQueryMembersInfoOnline(NIMResCode error_code, const std::string& tid, const std::list<TeamMemberProperty>& team_member_propertys)
{
	// Custom implementation
	std::string ids;
	for (auto iter = team_member_propertys.begin(); iter != team_member_propertys.end(); ++iter)
	{
		ids.append(iter->GetAccountID());
		ids.append(",");
	}
	char log[1024];
	sprintf_s(log, 1024, "tid: %s, member_count: %d\r\nids: %s", tid.c_str(), team_member_propertys.size(),ids.c_str());
	MessageBoxA(nullptr, log, "CallbackQueryMembersInfoOnline", 0);
}

void foo(const std::string& team_id)
{
	Team::QueryMuteListOnlineAsync(team_id, &CallbackQueryMembersInfoOnline);
}

Error codes

Code Description
200 The operation was successful.
803 Group does not exist
802 No permissions
C

Query muted members in a group by calling the nim_team_query_mute_list_online_async function.

Sample code:

nim_team_query_mute_list_online_async(const char *tid, const char *json_extension, nim_team_query_mute_list_cb_func cb, const void *user_data)

The result returned by the callback nim_team_query_mute_list_cb_func:

//nim_team_helper.cpp
void ParseTeamMemberPropertyJson(const Json::Value& team_member_prop_json, TeamMemberProperty& team_member_property)
{
	team_member_property.SetUserType((nim::NIMTeamUserType)team_member_prop_json[nim::kNIMTeamUserKeyType].asInt());
	if (team_member_property.GetUserType() != nim::kNIMTeamUserTypeApply && team_member_property.GetUserType() != nim::kNIMTeamUserTypeLocalWaitAccept)
	{
		team_member_property.SetAccountID(team_member_prop_json[nim::kNIMTeamUserKeyAccID].asString());
		team_member_property.SetNick(team_member_prop_json[nim::kNIMTeamUserKeyNick].asString());
		team_member_property.SetBits(team_member_prop_json[nim::kNIMTeamUserKeyBits].asUInt64());
		team_member_property.SetCreateTimetag(team_member_prop_json[nim::kNIMTeamUserKeyCreateTime].asUInt64());
		team_member_property.SetUpdateTimetag(team_member_prop_json[nim::kNIMTeamUserKeyUpdateTime].asUInt64());
		team_member_property.SetTeamID(team_member_prop_json[nim::kNIMTeamUserKeyID].asString());
		team_member_property.SetValid(team_member_prop_json[nim::kNIMTeamUserKeyValidFlag].asUInt() == 0 ? false : true);
		team_member_property.SetCustom(team_member_prop_json[nim::kNIMTeamUserKeyCustom].asString());
		team_member_property.SetMute(team_member_prop_json[nim::kNIMTeamUserKeyMute].asInt() == 1);
	}
}

//nim_cpp_team.cpp
static void CallbackQueryMembersOnline(int res_code, int count, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
	if (user_data)
	{
		Team::QueryTeamMembersOnlineCallback* cb_pointer = (Team::QueryTeamMembersOnlineCallback*)user_data;
		if (*cb_pointer)
		{
			Json::Value values;
			Json::Reader reader;
			std::list<TeamMemberProperty> members;
			if (reader.parse(PCharToString(result), values) && values.isArray())
			{
				auto size = values.size();
				for (size_t i = 0; i < size; i++)
				{
					TeamMemberProperty prop;
					ParseTeamMemberPropertyJson(values[i], prop);
					members.push_back(prop);
				}
			}
			(*cb_pointer)((NIMResCode)res_code, PCharToString(tid), members);
		}
		delete cb_pointer;
	}
}

API reference

C++
API
Description
AddManagersAsync Add an administrator
RemoveManagersAsync Remove an administrator
UpdateOtherNickAsync Edit the nickname of a member.
UpdateMyPropertyAsync Edit the personal profile of the current user in a group.
MuteMemberAsync Mute a specified member.
MuteAsync Mute all group members.
QueryTeamMembersInvitor Query the inviter of a group member.
QueryTeamMembersAsync Query the information about group members.
QueryTeamMemberAsync Query the specified group member information (asynchronous interface).
QueryTeamMemberBlock Query a specified group member by asynchronous call.
QueryMyAllMemberInfosAsync Query the information about the current user in all joined groups.
QueryMuteListOnlineAsync Query muted members in a group.
C
API
Description
nim_team_add_managers_async Add an administrator
nim_team_remove_managers_async Remove an administrator
nim_team_update_other_nick_async Edit the nickname of a member.
nim_team_update_my_property_async Edit the personal profile of the current user in a group.
nim_team_mute_member_async Mute a specified member.
nim_team_mute_async Mute all group members.
nim_team_query_members_invitor Query the inviter of a group member.
nim_team_query_team_members_async Query the information about group members.
nim_team_query_team_member_async Query the specified group member information (asynchronous interface).
nim_team_query_team_member_block Query a specified group member by asynchronous call.
nim_team_query_my_all_member_infos_async Query the information about the current user in all joined groups.
nim_team_query_mute_list_online_async Query muted members in a group.
Was this page helpful?
Yes
No
  • How it works
  • Prerequisites
  • Manage administrators
  • Add administrators
  • Remove an administrator
  • Edit the member profile
  • Edit the nickname of a group member
  • Edit the personal profile of the current user in a group
  • Mute members
  • Mute all group members
  • Mute a specified member
  • Query group members
  • Query the information about group members
  • Query a specified member
  • Query the information about the current user in all joined groups
  • Query the inviter of a group member
  • Query muted members in a group
  • API reference