IM 即时通讯
Windows/macOS
开发指南

群组管理

更新时间: 2023/03/09 18:19:09

网易云信 NIM SDK 提供了高级群形式的群组功能,支持用户创建、加入、退出、转让、修改、查询、解散群组,拥有完善的管理功能。

技术原理

网易云信 NIM SDK 的群组相关 API 都挂载在 nim::Team 模块中, nim::Team 提供群组操作相关接口,帮助您快速实现和使用群组的管理功能。

以上针对 C++ 接口接入,若需要以 C 接口接入,请参见 nim_team。若需要以 C# 接口接入,请参见 NIM.Team

群组相关事件监听

在进行群组操作前,您可以提前注册监听群相关事件。监听后,在进行群组管理相关操作时,会收到对应的通知。

C++

可以使用回调模板(OnTeamEventCallback)并调用 RegTeamEventCb 方法来监听群组事件通知。

其中群组事件的详细信息请参见 TeamEvent

示例代码:

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

foo()
{
	nim::Team::RegTeamEventCb(&OnTeamEventCallback);
}

对于部分查询接口,有单独的回调模板,具体请参见nim::Team

C

可以使用回调函数定义(nim_team_event_cb_func)并调用 nim_team_reg_team_event_cb 方法来监听群组事件通知。

其中群组通知事件的枚举请参见 NIMNotificationId

示例代码:

void CallbackTeamEvent(int error, int team_event, const char *tid, const char* str, const char *json_exten, const void *user_data)
{
	switch (team_event)
	{
	case kNIMNotificationIdLocalCreateTeam:
		...
	...	
	}
}

typedef void(*nim_team_reg_team_event_cb)(const char *json_extension, nim_team_event_cb_func cb, const void *user_data);

void foo()
{
	nim_team_reg_team_event_cb func = (nim_team_reg_team_event_cb) GetProcAddress(hInst, "nim_team_reg_team_event_cb");
	func(nullptr, &CallbackTeamEvent, nullptr);
}

对于部分查询接口,有单独的回调函数定义,具体请参见nim_team_def

C#

通过调用 RegisterCallbacks 方法来监听群组事件通知。

示例代码:

void OnTeamEventNotify(object sender, NIMTeamEventArgs e)
{
	if (e.Data.TeamEvent.NotificationType == NIMNotificationType.kNIMNotificationIdLocalGetTeamList)
	{
		···
	}
}

void foo()
{
	NIM.Team.TeamAPI.TeamEventNotificationHandler += OnTeamEventNotify;
}

对于部分查询接口,有单独的回调函数定义,具体请参见NIM.Team.Delegate

  • 由于获取群组信息和群成员信息需要跨进程异步调用,开发者最好能在第三方 APP 中做好群组和群成员信息缓存,查询群组和群成员信息时都从本地缓存中访问。在群组或者群成员信息有变化时,SDK 会告诉注册的观察者,此时,第三方 APP 可更新缓存,并刷新界面。
  • SDK 在收到群通知之后,会对本地缓存的群信息做出对应的修改,然后触发与修改相对应的监听事件回调。
  • 群通知是接收型的消息,开发者无法手动创建和发送群通知消息。

实现流程

本章节通过群主、管理员、普通成员之间的交互为例,介绍群组管理的实现流程。

uml diagram

创建群组

  • 创建群组时邀请的用户会收到类型为 kNIMSysMsgTypeTeamInvite 的系统通知(NIMSysMsgType)。
  • 若被邀请模式(NIMTeamBeInviteMode)为需要验证(kNIMTeamBeInviteModeNeedAgree),那么创建群组后,需要用户接受邀请,才会成为群成员。
C++

通过调用 CreateTeamAsyncEx 方法创建群组,创建者即为该群群主。

原创建群接口CreateTeamAsync已废弃。

参数说明:

参数 说明
team_info 群组信息,请参见TeamInfo 群组类型默认为 kNIMTeamTypeAdvanced 创建高级群,高级群拥有完善的成员权限体系及管理功能。为避免产生问题,不建议使用其他取值。
invitation_postscript 邀请入群的附言
ids 邀请加入的成员帐号列表
json_extension json扩展参数
目前可用于配置反垃圾相关参数
格式{"anti_spam_business_id":"{"textbid":"xxxx","picbid":"xxxx"}"}
cb 群通知的回调函数,请参见TeamEventCallback

示例代码:

void OnTeamEventCallback(const nim::TeamEvent& result)
{
	...
}
void foo()
{
	std::list<std::string> id_list;
	id_list.push_back("test1");
	id_list.push_back("test2");

	nim::TeamInfo tinfo;
	tinfo.SetName("test");
	tinfo.SetType(nim::kNIMTeamTypeAdvanced );
	nim::Team::CreateTeamAsyncEx(tinfo, id_list, "", &OnTeamEventCallback);
}

错误码:

状态码 说明
200 成功
810 邀请初始成员成功,并带上tinfo
414 成员不足
801 成员数超出限制
404 成员中有非法用户
C

通过调用 nim_team_create_team_async 方法创建群组,创建者即为该群群主。

示例代码:

void CallbackCreateTeam(int error, int team_event, const char *tid, const char* str, const char *json_exten, const void *user_data)
{
	...
}	
typedef void(*nim_team_create_team_async)(const char *team_info, const char *jsonlist_uids, const char *invitation_postscript, const char *json_extension, nim_team_event_cb_func cb, const void* user_data);
void foo()
{
	Json::Value team_info;
	team_info[kNIMTeamInfoKeyName] = ; //群名称
	team_info[kNIMTeamInfoKeyType] = ; //群类型
	team_info[kNIMTeamInfoKeyIntro] = ; //群介绍
	team_info[kNIMTeamInfoKeyJoinMode] = ; //群验证方式
	team_info[kNIMTeamInfoKeyAnnouncement] = ; //群公告

	Json::Value team_member;
	team_member.append("litianyi01");	
	team_member.append("litianyi02");

	nim_team_create_team_async func = (nim_team_create_team_async) GetProcAddress(hInst, "nim_team_create_team_async");
	func(team_info.toStyledString().c_str(), team_member.toStyledString().c_str(), "welcome to new team", nullptr, &CallbackCreateTeam, nullptr);
}
C#

通过调用 CreateTeam 方法创建群组,创建者即为该群群主。

示例代码:

void foo()
{
	NIM.Team.NIMTeamInfo tinfo = new NIM.Team.NIMTeamInfo();
	tinfo.Name = teamNameBox.Text;
	tinfo.Introduce = teamIntroBox.Text;
	tinfo.TeamType = NIM.Team.NIMTeamType.kNIMTeamTypeAdvanced;
	string[] uids = { "test1", "test2"};
	if (uids.Any())
	{
		NIM.Team.TeamAPI.CreateTeam(tinfo, uids, textBox1.Text, (a) =>
		{
			
		});
	}
}

加入群组

加入群组可以通过以下两种方式:

  • 用户接受邀请入群。
  • 用户主动申请入群。

邀请入群

邀请入群的模式可以通过 NIMTeamInviteMode 来定义,设为 kNIMTeamInviteModeManager,那么仅限群主和管理员可以邀请人进群;设为 kNIMTeamInviteModeEveryone ,那么群组内的所有人都可以邀请人进群。

C++

通过调用 InviteAsync 方法邀请其他用户进入群组。

  • 若群组的被邀请模式 NIMTeamBeInviteModekNIMTeamBeInviteModeNotNeedAgree ,那么无需验证,其他用户可直接加入群组。
  • 若群组的被邀请模式 NIMTeamBeInviteModekNIMTeamBeInviteModeNeedAgree ,那么需要被邀请用户同意才能加入群组。

如果在被邀请成员中存在成员拥有的群组数量已达上限,则会返回失败成员的账号列表。

参数说明:

参数 说明
tid 群ID
ids 邀请入群的用户账号列表
json_extension 自定义扩展字段
invitation_postscript 邀请附言,不需要的话设置为空
cb 邀请的回调函数
  • 发起邀请后,被邀请用户会收到 NIMSysMsgType 系统通知,其通知类型为kNIMSysMsgTypeTeamInvite
  • 被邀请用户可以调用 AcceptInvitationAsync 方法接受入群邀请,接受即入群。所有群成员会收到群组通知消息(消息类型为 kNIMMessageTypeNotification ),触发事件为kNIMNotificationIdTeamInviteAccept
  • 也可以调用 RejectInvitationAsync 方法拒绝入群邀请。拒绝后,邀请者会收到 NIMSysMsgType 系统通知,其通知类型为 kNIMSysMsgTypeTeamInviteReject

示例代码:

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

void foo()
{
	const std::list<std::string> friend_list;
	friend_list.push_back("test1");
	friend_list.push_back("test2");
	nim::Team::InviteAsync("123445", friend_list, "", &OnTeamEventCallback);
}

//接受入群邀请
void TeamEventCb(const nim::TeamEvent& team_event)
{
	···
}

void foo()
{
	nim::Team::AcceptInvitationAsync("12345", "my_id", &TeamEventCb);
}

//拒绝入群邀请
void TeamEventCb(const nim::TeamEvent& team_event)
{
	···
}

void foo()
{
	nim::Team::RejectInvitationAsync("12345", "my_id", "", &TeamEventCb);
}

错误码:

状态码 说明
200 成功
810 邀请初始成员成功,并带上timetag
801 成员数超出限制
802 没有权限
803 群不存在
404 非法用户
C

通过调用 nim_team_invite_async 方法邀请其他用户进入群组。

  • 若群组的被邀请模式 NIMTeamBeInviteModekNIMTeamBeInviteModeNotNeedAgree ,那么无需验证,其他用户可直接加入群组。

  • 若群组的被邀请模式 NIMTeamBeInviteModekNIMTeamBeInviteModeNeedAgree ,那么需要被邀请用户同意才能加入群组。

  • 发起邀请后,被邀请用户会收到 NIMSysMsgType 系统通知,其通知类型为kNIMSysMsgTypeTeamInvite

  • 被邀请用户可以调用 nim_team_accept_invitation_async 方法接受入群邀请,接受即入群。所有群成员会收到群组通知消息(消息类型为 kNIMMessageTypeNotification ),触发事件为kNIMNotificationIdTeamInviteAccept

  • 也可以调用 nim_team_reject_invitation_async 方法拒绝入群邀请。拒绝后,邀请者会收到 NIMSysMsgType 系统通知,其通知类型为 kNIMSysMsgTypeTeamInviteReject

示例代码:

void CallbackTeamChange(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
	//
}

typedef void(*nim_team_invite_async)(const char *tid, const char *jsonlist_uids, const char *invitation_postscript, const char *json_extension, nim_team_event_cb_func cb, const void* user_data);

void foo()
{
	Json::Value friend_list;
	friend_list.append("litianyi01");	
	friend_list.append("litianyi02");

	nim_team_invite_async func = (nim_team_invite_async) GetProcAddress(hInst, "nim_team_invite_async");
	func("12345", friend_list.toStyledString().c_str(), "welcome to new team", "", &CallbackCreateTeam, nullptr);
}

//接受入群邀请
void TeamEventCb(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
	···
}

typedef void(*nim_team_accept_invitation_async)(const char *tid, const char *invitor, const char *json_extension, nim_team_event_cb_func cb, const void* user_data);

void foo()
{
	nim_team_accept_invitation_async func = (nim_team_accept_invitation_async) GetProcAddress(hInst, "nim_team_accept_invitation_async");
	func("12345", "my_id", "", &TeamEventCb, nullptr);
}

//拒绝入群邀请
void TeamEventCb(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
	···
}

typedef void(*nim_team_reject_invitation_async)(const char *tid, const char *invitor, const char *reason, const char *json_extension, nim_team_event_cb_func cb, const void* user_data);

void foo()
{
	nim_team_reject_invitation_async func = (nim_team_reject_invitation_async) GetProcAddress(hInst, "nim_team_reject_invitation_async");
	func("12345", "my_id", "", "", &TeamEventCb, nullptr);
}
C#

通过调用 Invite 方法邀请其他用户进入群组。

  • 若群组的被邀请模式 NIMTeamBeInviteModekNIMTeamBeInviteModeNotNeedAgree ,那么无需验证,其他用户可直接加入群组。

  • 若群组的被邀请模式 NIMTeamBeInviteModekNIMTeamBeInviteModeNeedAgree ,那么需要被邀请用户同意才能加入群组。

  • 发起邀请后,被邀请用户会收到 NIMSysMsgType 系统通知,其通知类型为kNIMSysMsgTypeTeamInvite

  • 被邀请用户可以调用 AcceptTeamInvitation 方法接受入群邀请,接受即入群。所有群成员会收到群组通知消息(消息类型为 kNIMMessageTypeNotification ),触发事件为kNIMNotificationIdTeamInviteAccept

  • 也可以调用 RejectTeamInvitation 方法拒绝入群邀请。拒绝后,邀请者会收到 NIMSysMsgType 系统通知,其通知类型为 kNIMSysMsgTypeTeamInviteReject

示例代码:

void foo()
{
	string[] friend_list = { "test1", "test2" };
	NIM.Team.TeamAPI.Invite("12345", friend_list, "", (r) =>
	{
		if (r.TeamEvent.ResponseCode == NIM.ResponseCode.kNIMResTeamInviteSuccess)
		{
			foreach (var id in r.TeamEvent.IdCollection)
			{
				···
			}
		}
		else
		{
			MessageBox.Show("操作失败:" + r.TeamEvent.ResponseCode.ToString());
		}
	});
}

//接受入群邀请
NIM.Team.TeamAPI.AcceptTeamInvitation("12345", "my_id", (x) =>
{
	
});

//拒绝入群邀请
NIM.Team.TeamAPI.RejectTeamInvitation(string tid, string invitor, string reason, TeamChangedNotificationDelegate action);

申请入群

C++

通过调用 ApplyJoinAsync 方法申请加入群组。

  • 若群组的加入模式 NIMTeamJoinModekNIMTeamJoinModeNoAuth,那么无需验证,其他用户可直接加入群组。
  • 若群组的加入模式 NIMTeamJoinModekNIMTeamJoinModeNeedAuth ,那么需要群主或者群管理员同意才能加入群组。
  • 若群组的加入模式 NIMTeamJoinModekNIMTeamJoinModeRejectAll ,那么该群组不接受入群申请,仅能通过邀请方式入群。

参数说明:

参数 说明
tid 群ID
reason 申请附言
json_extension 自定义扩展字段
cb 申请入群的回调函数
  • 当用户发起入群申请后,该群群主和管理员会收到 NIMSysMsgType 系统通知,其通知类型为kNIMSysMsgTypeTeamApply
  • 群主和群管理员可以调用 PassJoinApplyAsync 方法接受入群申请,接受即入群。所有群成员会收到群组通知消息(消息类型为 kNIMMessageTypeNotification ),触发事件为kNIMNotificationIdTeamApplyPass
  • 群主和群管理员也可以调用 RejectJoinApplyAsync 方法拒绝入群申请。拒绝后,申请者会收到 NIMSysMsgType 系统通知,其通知类型为 kNIMSysMsgTypeTeamReject

示例代码:

void OnApplyJoinCb(const nim::TeamEvent& team_event)
{
	QLOG_APP(L"apply join: {0}") << team_event.res_code_;
	
	switch (team_event.res_code_)
	{
	case nim::kNIMResTeamAlreadyIn:
	{
		···
	}
	break;
	case nim::kNIMResSuccess:
	{
		···
	}
	break;
	case nim::kNIMResTeamApplySuccess:
		···
		break;
	default:
	{
		···
	}
	break;
	}
}

void foo()
{
	nim::Team::ApplyJoinAsync("12345", "", &OnApplyJoinCb);
}

//同意申请

void TeamEventCb(const nim::TeamEvent& team_event)
{
	switch (team_event.res_code_)
	{
	case nim::kNIMResTeamAlreadyIn:
	{
		···
	}
	break;
	case nim::kNIMResSuccess:
	{
		···
	}
	break;
	case nim::kNIMResTeamApplySuccess:
		···
		break;
	default:
	{
		···
	}
	break;
	}
}

void foo()
{
	nim::Team::PassJoinApplyAsync("12345", "my_id", &TeamEventCb);
}

//拒绝申请

void TeamEventCb(const nim::TeamEvent& team_event)
{
	switch (team_event.res_code_)
	{
	case nim::kNIMResTeamAlreadyIn:
	{
		···
	}
	break;
	case nim::kNIMResSuccess:
	{
		···
	}
	break;
	case nim::kNIMResTeamApplySuccess:
		···
		break;
	default:
	{
		···
	}
	break;
	}
}

void foo()
{
	nim::Team::RejectJoinApplyAsync("12345", "sender_id", "", &TeamEventCb);
}

错误码:

状态码 说明
200 成功
801 成员数超出限制
802 群验证方式为拒绝所有人申请
803 群不存在
805 群类型错误
808 申请成功
809 已在群组中
C

通过调用 nim_team_apply_join_async 方法申请加入群组。

  • 若群组的加入模式 NIMTeamJoinModekNIMTeamJoinModeNoAuth,那么无需验证,其他用户可直接加入群组。

  • 若群组的加入模式 NIMTeamJoinModekNIMTeamJoinModeNeedAuth ,那么需要群主或者群管理员同意才能加入群组。

  • 若群组的加入模式 NIMTeamJoinModekNIMTeamJoinModeRejectAll ,那么该群组不接受入群申请,仅能通过邀请方式入群。

  • 当用户发起入群申请后,该群群主和管理员会收到 NIMSysMsgType 系统通知,其通知类型为kNIMSysMsgTypeTeamApply

  • 群主和群管理员可以调用 nim_team_pass_join_apply_async 方法接受入群申请,接受即入群。所有群成员会收到群组通知消息(消息类型为 kNIMMessageTypeNotification ),触发事件为kNIMNotificationIdTeamApplyPass

  • 群主和群管理员也可以调用 nim_team_reject_join_apply_async 方法拒绝入群申请。拒绝后,申请者会收到 NIMSysMsgType 系统通知,其通知类型为 kNIMSysMsgTypeTeamReject

示例代码:

void TeamEventCb(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
	···
}

typedef void(*nim_team_apply_join_async)(const char *tid, const char *reason, const char *json_extension, nim_team_event_cb_func cb, const void* user_data);

void foo()
{
	nim_team_apply_join_async func = (nim_team_apply_join_async) GetProcAddress(hInst, "nim_team_apply_join_async");
	func("12345", "", "", &TeamEventCb, nullptr);
}

//同意入群申请
void TeamEventCb(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
	···
}

typedef void(*nim_team_pass_join_apply_async)(const char *tid, const char *applicant_id, const char *json_extension, nim_team_event_cb_func cb, const void* user_data);

void foo()
{
	nim_team_pass_join_apply_async func = (nim_team_pass_join_apply_async) GetProcAddress(hInst, "nim_team_pass_join_apply_async");
	func("12345", "my_id", "", &TeamEventCb, nullptr);
}

//拒绝入群申请
void TeamEventCb(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
	···
}

typedef void(*nim_team_reject_join_apply_async)(const char *tid, const char *applicant_id, const char *reason, const char *json_extension, nim_team_event_cb_func cb, const void* user_data);

void foo()
{
	nim_team_reject_join_apply_async func = (nim_team_reject_join_apply_async) GetProcAddress(hInst, "nim_team_reject_join_apply_async");
	func("12345", "sender_id", "", &TeamEventCb, nullptr);
}

C#

通过调用 ApplyForJoiningTeam 方法申请加入群组。

  • 若群组的加入模式 NIMTeamJoinModekNIMTeamJoinModeNoAuth,那么无需验证,其他用户可直接加入群组。

  • 若群组的加入模式 NIMTeamJoinModekNIMTeamJoinModeNeedAuth ,那么需要群主或者群管理员同意才能加入群组。

  • 若群组的加入模式 NIMTeamJoinModekNIMTeamJoinModeRejectAll ,那么该群组不接受入群申请,仅能通过邀请方式入群。

  • 当用户发起入群申请后,该群群主和管理员会收到 NIMSysMsgType 系统通知,其通知类型为kNIMSysMsgTypeTeamApply

  • 群主和群管理员可以调用 AgreeJoinTeamApplication 方法接受入群申请,接受即入群。所有群成员会收到群组通知消息(消息类型为 kNIMMessageTypeNotification ),触发事件为kNIMNotificationIdTeamApplyPass

  • 群主和群管理员也可以调用 RejectJoinTeamApplication 方法拒绝入群申请。拒绝后,申请者会收到 NIMSysMsgType 系统通知,其通知类型为 kNIMSysMsgTypeTeamReject

示例代码:

NIM.Team.TeamAPI.ApplyForJoiningTeam("12345", "", (x) =>
{
	
});

//同意入群申请
NIM.Team.TeamAPI.AgreeJoinTeamApplication("12345", "my_id", (x) =>
{
	
});
//拒绝入群申请
NIM.Team.TeamAPI.RejectJoinTeamApplication("12345", "sender_id", "", (x) =>
{
	
});

转让群组

只有群主才有转让群组的权限。

C++

通过调用 TransferTeamAsync 方法将群组转让给其他成员。

  • 转让群后, 群主身份转移,所有群成员会收到群组通知消息(消息类型为 kNIMMessageTypeNotification ),触发事件为kNIMNotificationIdTeamOwnerTransfer
  • 如果转让群的同时离开群, 那么相当于同时调用quitTeam主动退群。所有群成员会收到群组通知消息(消息类型为 kNIMMessageTypeNotification ),触发事件为kNIMNotificationIdTeamLeave

参数说明:

参数 说明
tid 群ID
new_owner_id 转让后的群主账号
is_leave 转让群的同时是否退出该群
true:退出
false:不退出,身份变为普通群成员
json_extension 自定义扩展字段
cb 转让群主的回调函数

示例代码:

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

foo()
{
	nim::Team::TransferTeamAsync("tid_", "user_id", false, &OnTeamEventCallback);
}

错误码:

状态码 说明
200 成功
802 没有权限
803 群不存在
805 群类型错误
806 群数量超出限制
C

通过调用 nim_team_transfer_team_async 方法将群组转让给其他成员。

  • 转让群后, 群主身份转移,所有群成员会收到群组通知消息(消息类型为 kNIMMessageTypeNotification ),触发事件为kNIMNotificationIdTeamOwnerTransfer
  • 如果转让群的同时离开群, 那么相当于同时调用nim_team_leave_async主动退群。所有群成员会收到群组通知消息(消息类型为 kNIMMessageTypeNotification ),触发事件为kNIMNotificationIdTeamLeave

示例代码:

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_transfer_team_async)(const char *tid, const char *new_owner, bool is_leave, const char *json_extension, nim_team_event_cb_func cb, const void* user_data);

void foo()
{
	nim_team_transfer_team_async func = (nim_team_transfer_team_async) GetProcAddress(hInst, "nim_team_transfer_team_async");
	func("tid", "user_id", false, nullptr, &CallbackTeamOperate, nullptr);
}
C#

通过调用 TransferTeamAdmin 方法将群组转让给其他成员。

  • 转让群后, 群主身份转移,所有群成员会收到群组通知消息(消息类型为 kNIMMessageTypeNotification ),触发事件为kNIMNotificationIdTeamOwnerTransfer
  • 如果转让群的同时离开群, 那么相当于同时调用LeaveTeam主动退群。所有群成员会收到群组通知消息(消息类型为 kNIMMessageTypeNotification ),触发事件为kNIMNotificationIdTeamLeave

示例代码:

NIM.Team.TeamAPI.TransferTeamAdmin("_teamId", "user_id", false, (ret) =>
{
	···
});

退出群组

退出群组可以通过以下两种方式:

  • 群主或群组管理员将用户踢出群组。所有群成员会收到群组通知消息(消息类型为 kNIMMessageTypeNotification ),触发事件为kNIMNotificationIdTeamKick
  • 用户主动退群。主动退群后,所有群成员会收到群组通知消息(消息类型为 kNIMMessageTypeNotification ),触发事件为kNIMNotificationIdTeamLeave

踢人出群

  • 只有群主和管理员才能将成员踢出群组。
  • 管理员不能踢群主和其他管理员。
C++

通过调用 KickAsync 方法将成员踢出群组。

参数说明:

参数 说明
tid 群ID
ids 被踢出的群成员账号列表
json_extension 自定义扩展字段
cb 踢人的回调函数

示例代码:

Team::KickAsync("tid", {123456, 456789}, [this](const TeamEvent& team_event) {
	// process team_event
});

错误码:

状态码 说明
200 成功
403 被踢的是管理员或群主
404 非法用户
801 群人数超出限制
802 没有权限
803 群不存在
C

通过调用 nim_team_kick_async 方法将成员踢出群组。

示例代码:

void TeamEventCb(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
	···
}

typedef void(*nim_team_kick_async)(const char *tid, const char *jsonlist_uids, const char *json_extension, nim_team_event_cb_func cb, const void* user_data);

void foo()
{
	nim_team_kick_async func = (nim_team_kick_async) GetProcAddress(hInst, "nim_team_kick_async");

	Json::Value json_value;
	json_value.append("litianyi01");	
	json_value.append("litianyi02");

	func("12345", json_value.toStyledString().c_str(), "", &TeamEventCb, nullptr);
}

C#

通过调用 KickMemberOutFromTeam 方法将成员踢出群组。

示例代码:

NIM.Team.TeamAPI.KickMemberOutFromTeam("12345", new string[] {"test_user"}, (a) =>
{
	if (a.TeamEvent.ResponseCode == NIM.ResponseCode.kNIMResSuccess)
	{
		···
	}
});

主动退群

除群主(需先转让群主)外,其他用户均可以直接主动退群。

C++

通过调用 LeaveAsync 方法主动退出群组。

参数说明:

参数 说明
tid 群ID
json_extension 自定义扩展字段
cb 退群的回调函数

示例代码:

void TeamEventCb(const nim::TeamEvent& team_event)
{
	···
}

void foo()
{
	nim::Team::LeaveAsync("12345", &TeamEventCb);
}

错误码:

状态码 说明
200 成功
803 群不存在
804 用户不在群组中
C

通过调用 nim_team_leave_async 方法主动退出群组。

示例代码:

void TeamEventCb(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
	···
}

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

void foo()
{
	nim_team_leave_async func = (nim_team_leave_async) GetProcAddress(hInst, "nim_team_leave_async");

	func("12345", "", &TeamEventCb, nullptr);
}
C#

通过调用 LeaveTeam 方法主动退出群组。

示例代码:

NIM.Team.TeamAPI.LeaveTeam("12345", (ret) =>
{
	if (ret.TeamEvent.ResponseCode == NIM.ResponseCode.kNIMResSuccess)
	{
		···
	}
});

解散群组

解散群后, 所有群成员会收到群组通知消息(消息类型为 kNIMMessageTypeNotification ),触发事件为kNIMNotificationIdTeamDismiss

只有群主才能解散群组。

C++

通过调用 DismissAsync 方法解散群组。

参数说明:

参数 说明
tid 群ID
json_extension 自定义扩展字段
cb 解散群的回调函数

示例代码:

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

foo()
{
	nim::Team::DismissAsync("tid_", &OnTeamEventCallback);
}

错误码:

状态码 说明
200 成功
802 没有权限
803 群不存在
C

通过调用 nim_team_dismiss_async 方法解散群组。

示例代码:

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_dismiss_async)(const char *tid, const char *json_extension, nim_team_event_cb_func cb, const void* user_data);

void foo()
{
	nim_team_dismiss_async func = (nim_team_dismiss_async) GetProcAddress(hInst, "nim_team_dismiss_async");
	func("tid", nullptr, &CallbackTeamOperate, nullptr);
}
C#

通过调用 DismissTeam 方法解散群组。

示例代码:

NIM.Team.TeamAPI.DismissTeam("_teamId", (ret) =>
{
	···
});

修改群组信息

当用户更新群组信息后,所有群成员会收到群组通知消息(消息类型为 kNIMMessageTypeNotification ),触发事件为kNIMNotificationIdTeamUpdate

修改群信息需要权限。若该群组的群信息修改权限(NIMTeamUpdateInfoMode)为 kNIMTeamUpdateInfoModeManager,那么只有群主和管理员才能修改群组信息;若为 kNIMTeamUpdateInfoModeEveryone ,则群组内的所有人都可以修改群组信息。

C++

通过调用 UpdateTeamInfoAsync 方法修改群组的信息。

参数说明:

参数 说明
tid 群ID
team_info 待更新的群组信息,具体请参见TeamInfo
json_extension 自定义扩展字段
cb 个更新群组信息的回调函数

示例代码:

void OnUpdateBroadCb(const nim::TeamEvent& team_event)
{
	if (team_event.res_code_ == 200)
	{
		···
	}
}

void foo()
{
	Json::Value broad;
	broad["title"] = "title";
	broad["content"] = "内容";
	broad["creator"] = "test_user";

	Json::Value broads;
	broads.append(broad);

	Json::FastWriter writer;
	nim::TeamInfo param;
	param.SetAnnouncement(writer.write(broads));
	param.SetTeamID("tid_");

	nim::Team::UpdateTeamInfoAsync("tid_", param, &OnUpdateBroadCb);
}

错误码:

状态码 说明
200 成功
802 没有权限
803 群不存在
C

通过调用 nim_team_update_team_info_async 方法修改群组的信息。

示例代码:

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_update_team_info_async)(const char *tid, const char *json_info, const char *json_extension, nim_team_event_cb_func cb_func, const void* user_data);

void foo()
{
	Json::Value values;
	values[kNIMTeamInfoKeyID] = "tid";	
	values[kNIMTeamInfoKeyAnnouncement] = "123"; //修改群公告,同样的,目前可以修改群名称,群简介,具体参阅api文档

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

通过调用 UpdateTeamInfo 方法修改群组的信息。

示例代码:

void foo()
{
	NIM.Team.NIMTeamInfo tinfo = new NIM.Team.NIMTeamInfo();
	tinfo.Announcement = "公告";
	tinfo.TeamId = "tid";
	
	NIM.Team.TeamAPI.UpdateTeamInfo("tid", tinfo, (ret) =>
	{
		if (ret.TeamEvent.ResponseCode == NIM.ResponseCode.kNIMResSuccess)
		{
			···
		}
	});
}

查询群组信息

SDK 在程序启动时会对本地群信息进行同步,所以只需要调用本地缓存接口获取群即可。

SDK 支持批量获取自己加入的所有群组、根据单个群 ID 查询群组、以及远程(从服务器)获取群信息功能。

本地查询自己加入的群组列表

查询的是本地所有有效群。有效群需要满足两个条件:群有效以及我在群里。

C++

通过调用QueryAllMyTeamsAsync方法从本地查询自己加入的所有群组列表。

示例代码如下:

Team::QueryAllMyTeamsAsync([this](int count, const std::list<std::string>& team_id_list) {
	std::string ids;
	for (auto&& tid : team_id_list) {
		ids += tid + ";";
	}
	std::cout << "[Team] QueryAllMyTeamsAsync. count: " << count << ", team_ids: " << ids << std::endl;
});
C

通过调用nim_team_query_all_my_teams_async方法从本地查询自己加入的所有群组列表。

示例代码如下:

static void CallbackFunc(int team_count, const char* result, const char* json_extension, const void* user_data){
    printf("team_count: %d\n", team_count);
    printf("result: %s\n", result);
};
nim_team_query_all_my_teams_async("", &CallbackFunc, nullptr);
C#

通过调用QueryAllMyTeams方法从本地查询自己加入的所有群组列表。

本地查询自己加入的所有群组信息

  • 默认查询的是本地所有有效群信息。有效群需要满足两个条件:群有效以及我在群里。
  • SDK 2.7.0 支持通过配置扩展参数(json_extension)条件获取缓存中有的无效群(我已不在里面的群或者解散的群),例如 "{"include_invalid" : true}"。
  • 在回调函数中,开发者通过解析群组信息 JSON 后,通过 kNIMTeamInfoKeyValidFlag 字段区分该群为存在的群还是已经解散的群,通过 kNIMTeamInfoKeyMemberValid 字段区分自己是否还在该群。
C++

通过调用QueryAllMyTeamsInfoAsync方法从本地查询自己加入的所有群组信息。

示例代码如下:

Team::QueryAllMyTeamsInfoAsync([this](int count, const std::list<TeamInfo>& team_info_list) {
	std::cout << "count: " << count << std::endl;
	for (auto& info : team_info_list) {
		// process team_info
	}
});
C

通过调用nim_team_query_all_my_teams_info_async方法从本地查询自己加入的所有群组信息。

示例代码如下:

static void CallbackFunc(int team_count, const char* result, const char* json_extension, const void* user_data){
	printf("team_count: %d, result: %s, json_extension: %s\n", team_count, result, json_extension);
};
nim_team_query_all_my_teams_info_async("", &CallbackFunc, nullptr);
C#

通过调用QueryAllMyTeamsInfo方法从本地查询自己加入的所有群组信息。

查询指定群组信息

C++

通过异步调用QueryTeamInfoAsync方法或者同步调用QueryTeamInfoBlock方法从本地查询指定群组信息。

示例代码如下:

//异步调用
Team::QueryTeamInfoAsync(params["tid"].asString(), [this](const std::string& tid, const TeamInfo& result) {
	std::cout << "[Team] QueryTeamInfoAsync. team_id: " << tid << std::endl;
});

//同步调用
TeamInfo result = Team::QueryTeamInfoBlock("tid");
std::cout << "[Team] QueryTeamInfoAsync. team_id: " << result.GetTeamID() << std::endl;
  • 异步调用 QueryTeamInfoAsync时,如果本地没有该群组信息,则自动去服务器查询。
  • 同步调用 QueryTeamInfoBlock 时,仅查询本地,不会去服务器请求。如果自己不在该群组中,接口返回的可能是过期信息,如需最新的,请调用 QueryTeamInfoOnlineAsync 方法去服务器查询。
  • 同步接口,可能会堵塞 NIM 内部线程,请谨慎使用。

:::

C

通过异步调用nim_team_query_team_info_async方法或者同步调用nim_team_query_team_info_block方法从本地查询指定群组信息。

示例代码如下:

//异步调用
static void CallbackFunc(const char* tid, const char* result, const char* json_extension, const void* callback){
	std::cout << "tid:" << tid << std::endl;
};
nim_team_query_team_info_async("tid", "", &CallbackFunc, nullptr);

//同步调用
const char* team_info = nim_team_query_team_info_block("tid");
prinf("team_info: %s\n", team_info);
  • 异步调用 nim_team_query_team_info_async时,如果本地没有该群组信息,则自动去服务器查询。
  • 同步调用 nim_team_query_team_info_block 时,仅查询本地,不会去服务器请求。如果自己不在该群组中,接口返回的可能是过期信息,如需最新的,请调用 nim_team_query_team_info_online_async 方法去服务器查询。
  • 同步接口,可能会堵塞 NIM 内部线程,请谨慎使用。

:::

C#

通过异步调用QueryCachedTeamInfo方法或者同步调用QueryCachedTeamInfo方法从本地查询指定群组信息。

  • 异步调用时,如果本地没有该群组信息,则自动去服务器查询。
  • 同步调用时,仅查询本地,不会去服务器请求。如果自己不在该群组中,接口返回的可能是过期信息,如需最新的,请调用 QueryTeamInfoOnline 方法去服务器查询。
  • 同步接口,可能会堵塞 NIM 内部线程,请谨慎使用。

:::

批量查询指定群组信息

C++

通过调用GetTeaminfoList方法根据群组 ID 批量查询指定群组信息。

示例代码如下:

Team::GetTeaminfoList({"tid1", "tid2", "tid3"}, [](NIMResCode error_code, const std::list<nim::TeamInfo>& team_info_list, const std::list<std::string>& fail_list){
	std::cout << "GetTeaminfoList error_code:" << error_code << std::endl;
});
C

通过调用nim_team_get_team_info_list方法根据群组 ID 批量查询指定群组信息。

示例代码如下:

static void CallbackFunc(int code, const char* tinfo_list, const char* fail_tid_list, const void* user_data){
	printf("nim_team_get_team_info_list code: %d", code);
};
nim_team_get_team_info_list("[\"tid1\", \"tid2\", \"tid3\"]", &CallbackFunc, NULL);

群组信息 SDK 本地存储说明:

  • 解散群、退出群或者被移出群时,本地数据库会继续保留该群组信息,只是设置了无效标记,此时依然可以查询该群组信息。 如果用户手动清空全部本地数据,下次登录同步时,服务器将不同步无效的群组,用户将无法取得已退出群的群组信息。

  • 群解散后,从服务器查询群组信息时结果将返回空值。

从服务器查询指定群组

C++

通过调用QueryTeamInfoOnlineAsync方法从服务器查询指定的群组信息。示例代码如下:

Team::QueryTeamInfoOnlineAsync("tid", [this](const TeamEvent& team_event) {
	// process team_event
});
C

通过调用nim_team_query_team_info_online_async方法从服务器查询指定的群组信息。示例代码如下:

static void CallbackTeamChange(int res_code,
    int notification_id,
    const char* tid,
    const char* result,
    const char* json_extension,
    const void* user_data) {
    // process result
}
nim_team_query_team_info_online_async("tid", "", &CallbackTeamChange, NULL);
C#

通过调用QueryTeamInfoOnline方法从服务器查询指定的群组信息。

群组检索

C++

通过调用QueryTeamInfoByKeywordAsync方法搜索与关键字匹配的所有群信息。示例代码如下:

Team::QueryTeamInfoByKeywordAsync("keyword", [this](int count, const std::list<TeamInfo>& team_info_list) {
	std::cout << "QueryTeamInfoByKeywordAsync count: " << count << std::endl;
});
C

通过调用nim_team_query_teams_info_by_keyword方法搜索与关键字匹配的所有群信息。示例代码如下:

static void CallbackQueryAllMyTeamsInfo(int team_count, const char* result, const char* json_extension, const void* user_data) {
    // process result
}
nim_team_query_teams_info_by_keyword("keyword", &CallbackQueryAllMyTeamsInfo, "", NULL);

API 参考

C++
API
说明
RegTeamEventCb 监听群组事件通知
CreateTeamAsync 创建群组
InviteAsync 邀请入群
AcceptInvitationAsync 接受入群邀请
RejectInvitationAsync 拒绝入群邀请
ApplyJoinAsync 申请入群
PassJoinApplyAsync 接受入群申请
RejectJoinApplyAsync 拒绝入群申请
KickAsync 踢人出群
LeaveAsync 主动退群
TransferTeamAsync 转让群组
DismissAsync 解散群组
UpdateTeamInfoAsync 修改群组的信息
QueryAllMyTeamsAsync 从本地查询自己加入的所有群组
QueryAllMyTeamsInfoAsync 从本地查询自己加入的所有群组信息
QueryTeamInfoAsync 查询指定群组信息(异步接口)
QueryTeamInfoBlock 查询指定群组信息(同步接口)
GetTeaminfoList 根据群组 ID 批量查询指定群组信息
QueryTeamInfoOnlineAsync 从服务器查询指定的群组信息
QueryTeamInfoByKeywordAsync 搜索与关键字匹配的所有群信息
C
API
说明
nim_team_reg_team_event_cb 监听群组事件通知
nim_team_create_team_async 创建群组
nim_team_invite_async 邀请入群
nim_team_accept_invitation_async 接受入群邀请
nim_team_reject_invitation_async 拒绝入群邀请
nim_team_apply_join_async 申请入群
nim_team_pass_join_apply_async 接受入群申请
nim_team_reject_join_apply_async 拒绝入群申请
nim_team_kick_async 踢人出群
nim_team_leave_async 主动退群
nim_team_transfer_team_async 转让群组
nim_team_dismiss_async 解散群组
nim_team_update_team_info_async 修改群组的信息
nim_team_query_all_my_teams_async 从本地查询自己加入的所有群组
nim_team_query_all_my_teams_info_async 从本地查询自己加入的所有群组信息
nim_team_query_team_info_async 查询指定群组信息(异步接口)
nim_team_query_team_info_block 查询指定群组信息(同步接口)
nim_team_get_team_info_list 根据群组 ID 批量查询指定群组信息
nim_team_query_team_info_online_async 从服务器查询指定的群组信息
nim_team_query_teams_info_by_keyword 搜索与关键字匹配的所有群信息
C#
API
说明
RegisterCallbacks 监听群组事件通知
CreateTeam 创建群组
Invite 邀请入群
AcceptTeamInvitation 接受入群邀请
RejectTeamInvitation 拒绝入群邀请
ApplyForJoiningTeam 申请入群
AgreeJoinTeamApplication 接受入群申请
RejectJoinTeamApplication 拒绝入群申请
KickMemberOutFromTeam 踢人出群
LeaveTeam 主动退群
TransferTeamAdmin 转让群组
DismissTeam 解散群组
UpdateTeamInfo 修改群组的信息
QueryAllMyTeams 从本地查询自己加入的所有群组
QueryAllMyTeamsInfo 从本地查询自己加入的所有群组信息
QueryCachedTeamInfo 查询指定群组信息(异步接口)
QueryCachedTeamInfo 查询指定群组信息(同步接口)
QueryTeamInfoOnline 从服务器查询指定的群组信息
此文档是否对你有帮助?
有帮助
去反馈
  • 技术原理
  • 群组相关事件监听
  • 实现流程
  • 创建群组
  • 加入群组
  • 邀请入群
  • 申请入群
  • 转让群组
  • 退出群组
  • 踢人出群
  • 主动退群
  • 解散群组
  • 修改群组信息
  • 查询群组信息
  • 本地查询自己加入的群组列表
  • 本地查询自己加入的所有群组信息
  • 查询指定群组信息
  • 批量查询指定群组信息
  • 从服务器查询指定群组
  • 群组检索
  • API 参考