群组

群组（下文简称群）有固定的成员，适合同事群、家长群、兴趣群等场景。用户可以在客户端建群、邀请他人、申请加入公开群、通过入群链接加入；群主和管理员可以修改群资料、管理成员、审批入群申请。

Web SDK 把“我的群”和读取过的群成员列表保存在本地，以可订阅的列表提供：登录、重连后自动同步，其他成员和其他设备上的变化实时反映到列表中。入群申请、邀请这类只需要翻页查看的数据按页查询。

本页介绍群本身和成员的操作。发送群消息见消息（目标写成 { to_group: group_id }），群文件见文件。群的概念（类型、角色、设置、状态）与服务端相同，完整的规则见服务端的群组管理。

基本概念

群类型

`type`	说明
`private`	私有群，默认。只能由成员邀请、通过入群链接加入或由你的服务端添加；非成员看不到这个群，对它的任何操作都得到 `not_found`
`public`	公开群。用户可以搜索到它，看到名称、头像、简介和人数，并申请加入

角色与权限

操作	群主 `owner`	管理员 `admin`	普通成员 `member`
修改群资料和设置	可以	可以（群类型除外）	不可以
邀请他人	可以	可以	按群设置 `member_invite`
移出、禁言成员，管理群黑名单	可以	只能处理普通成员	不可以
开启全员禁言，审批入群申请，生成入群链接	可以	可以	不可以
设置管理员、转让群主、解散群	可以	不可以	不可以
修改自己的群昵称	可以	可以	可以

每个群最多 20 个管理员。群主不能被移出、禁言或加入群黑名单；群主要退出，须先转让群主。

群设置

字段	取值	说明
`member_invite`	`free`（默认）、`approval`、`disabled`	普通成员能否邀请他人：直接邀请、邀请后要群主或管理员审批、不能邀请
`join_mode`	`approval`（默认）、`free`	公开群的申请方式：需要审批、申请即加入。私有群为 `null`，不能设置
`mute_all`	`true`、`false`	全员禁言，开启后只有群主和管理员可以发言
`max_members`	只读	群的人数上限，只能由你的服务端或控制台设置

建群

用户在客户端建群时自己是群主，可以同时邀请初始成员（最多 100 人）。初始成员按邀请的规则处理：对方的入群设置为需要确认时，他收到一条邀请，接受后才入群。

const group = await im.groups.create({
  name: '产品研发群',
  type: 'private',
  description: '产品和研发日常沟通',
  members: ['lisi', 'wangwu', 'zhaoliu'],
  message: '拉你进项目群',          // 给需要确认的被邀请人看的附言
});

for (const r of group.results) {
  if ('code' in r) console.warn(`${r.username} 没有加入：${r.code}`);
  else if (r.status === 'invited') console.log(`${r.username} 需要确认后入群`);
}

返回值是新群的 GroupInfo，另加 results，按请求的顺序列出每个初始成员的结果，见 GroupMemberResult。初始成员加入失败不影响建群。
新群随即出现在“我的群”列表中。
应用在运行策略中关闭了客户端建群时，以 permission_denied 拒绝。可以先读取 im.config?.client_group_create_enabled 决定是否显示建群入口。
本人加入的群数已满时以 limit_exceeded（details.reason 为 user_group_limit）拒绝，不建群；应用的群数已达套餐的上限时为 app_group_limit。
群名称、简介、公告、头像要经过内容安全检查，不通过时以 content_rejected 拒绝，details.field 为字段名。

建群不会自动重试

网络错误或超时后，SDK 先刷新本人的群列表：找到这次新建的群（群主是本人、创建时间在这次调用之后）的按成功返回，这时 results 为空数组，可以用 members() 查看实际入群的人；找不到的以 timeout 拒绝，由用户决定是否再建。遇到 rate_limited 时请提示用户，不要自动重试。

我的群

im.groups.list() 返回本人加入的全部群的可订阅列表，每项为 GroupView，按群名排序。登录后 SDK 自动同步；建群、入群、退群、被移出、群解散，以及群资料的变化都会反映到列表中。列表不再显示时调用 dispose()。

const groups = im.groups.list();
groups.subscribe(() => {
  const { items, loading } = groups.getSnapshot();
  if (!loading) render(items.map((g: GroupView) => `${g.group.name || '群聊'}（${g.group.member_count}）`));
});

本人在群里的角色、群昵称和禁言状态在 group.self 中：

const view = await im.groups.get('1840012345678901');
const self = view?.group.self;
const canManage = self?.role === 'owner' || self?.role === 'admin';

im.groups.get(group_id) 先读本地，本地有就直接返回；本地没有（如别人分享的公开群）或 refresh: true 时向服务端查询。看不到的群（不存在、本人不是成员的私有群）返回 undefined。
已离开的群 in_my_groups 为 false，group 为离开前最后一次的信息，会话列表仍可以用它显示群名和头像。
一次查询多个群用 im.groups.lookup(group_ids)（最多 100 个），本人不是成员的公开群只返回公开的字段，看不到的群不在结果中。

群资料和我的群列表的变化以 groups.changed 事件通知，载荷中 upserted 为新增或变化的群，removed 为离开了“我的群”的群。

修改群资料和设置

群主和管理员可以修改群资料和设置，只提交传入的字段。群类型只有群主能改。修改后群的在线成员收到变化，本地的群信息随之更新。

await im.groups.update('1840012345678901', {
  name: '产品研发群（2 期）',
  announcement: '本周五发布 2.3 版本',
  attributes: { project_id: 'P-1024', old_key: null },   // 按项合并，null 删除这个键
  member_invite: 'approval',
});

公开群改为私有群时，尚未处理的入群申请全部失效；私有群改为公开群时，申请方式默认为需要审批。
为私有群设置 join_mode 以 invalid_argument 拒绝。
多人可能同时修改时，带上读取到的 group.info_version 作为 version，群资料已被别人修改时以 version_conflict 拒绝，不做任何修改。
修改的名称、简介、公告、头像要经过内容安全检查，不通过时以 content_rejected 拒绝。
群被封禁时以 group_disabled 拒绝。

设置群头像

群头像要先以用途 group_avatar 上传，得到公开地址后再写入群资料（建群前就可以上传）：

async function changeGroupAvatar(file: File) {
  const info = await im.files.upload(file, { purpose: 'group_avatar' });
  await im.groups.update(groupId, { avatar_url: info.url });
}

成员列表

im.groups.members(group_id) 返回群成员的可订阅列表，按群主、管理员、普通成员排列，同一角色按入群时间排列。只有成员可以查看。

const members = im.groups.members(groupId);
members.subscribe(() => {
  const { items, loading, error } = members.getSnapshot();
  if (error) showToast(error.message);
  else if (!loading) render(items.map((m: GroupMember) => m.group_nickname || m.nickname || m.username));
});

// 只看管理员、只看被禁言的成员
const admins = im.groups.members(groupId, { role: 'admin' });
const muted = im.groups.members(groupId, { muted: true });

第一次打开某个群的成员列表时，SDK 获取全部成员（最多 5000 人）并保存在本地；之后再打开时只检查是否有变化，页面刷新后同样有效。筛选在本地进行。
成员的加入、离开，角色、群昵称、禁言的变化实时反映到列表中，同时发出 groupMembers.changed。
列表不再显示时调用 dispose()。

只需要显示少数人的群昵称（如消息发送者）时，不必取整个成员列表，用 lookupMembers（最多 100 人，不是成员的不在结果中）：

const found = await im.groups.lookupMembers(groupId, ['lisi', 'wangwu']);

群的在线人数（需要应用开启在线状态且 presence_scope 为 all，否则以 permission_denied 拒绝）：

const { online_count } = await im.groups.onlineCount(groupId);

同一个群 30 秒内重复查询直接返回上一次的结果。

邀请成员

一次最多邀请 100 人，可以带附言。结果按请求的顺序逐个给出，某个人失败不影响其他人：

const results = await im.groups.invite(groupId, ['sunqi', 'zhouba'], { message: '欢迎加入' });
for (const r of results) {
  if ('code' in r) showToast(`${r.username}：${r.code}`);
}

成功的 status：

`status`	说明
`joined`	已入群
`invited`	对方需要确认，已发出邀请，见被邀请时是否需要确认
`pending_review`	本人是普通成员且群设置为邀请需要审批，等待群主或管理员审批
`already_member`	原本就是成员

失败的项带 code，常见的有：permission_denied（对方在群黑名单中，details.reason 为 group_blacklisted；或被加群前回调拒绝）、limit_exceeded（群已满 group_member_limit，或对方的群数已满 user_group_limit）、user_blocked（对方把本人拉黑了）、not_friend（应用只允许邀请好友）、rate_limited（declined_cooldown：对方 24 小时内拒绝过这个群的邀请或主动退出了这个群；request_rate、group_join_rate：邀请或入群过于频繁）、not_found（用户不存在）。

整个请求失败的情况：普通成员在 member_invite 为 disabled 的群里邀请（permission_denied），群被封禁（group_disabled）。

移出成员

群主和管理员可以移出成员（管理员只能移出普通成员），一次最多 100 人。结果中 removed 为已移出，not_member 为原本就不是成员。不能用它移出自己，请用退出群。

await im.groups.removeMembers(groupId, ['zhouba']);

设置管理员

群主可以把成员设为管理员或取消管理员，每个群最多 20 个管理员（超出以 limit_exceeded 拒绝，details.reason 为 admin_limit）。

await im.groups.setRole(groupId, 'lisi', 'admin');
await im.groups.setRole(groupId, 'lisi', 'member');   // 取消管理员

群昵称与成员属性

每个成员可以修改自己的群昵称；群主和管理员也可以修改级别比自己低的成员的群昵称和成员属性。成员属性按项合并，值为 null 的键被删除。

const me = im.auth.currentUser!.username;
await im.groups.updateMember(groupId, me, { group_nickname: '李四-研发' });
await im.groups.updateMember(groupId, 'wangwu', { attributes: { title: '后端' } });

群昵称最长 64 个字符，传空字符串表示清除；要经过内容安全检查。显示名字时可以用 @deeprespond/im-web/render 中的 displayName(im, username, { group_id })，它按好友备注、群昵称、昵称、用户名的顺序取第一个非空的。

禁言

禁言成员

群主和管理员可以禁言成员（管理员只能禁言普通成员），省略时长为永久禁言。被禁言的成员发送群消息时得到 group_muted（details.reason 为 member）。

await im.groups.mute(groupId, 'zhouba', { duration_seconds: 3600 });   // 禁言 1 小时
await im.groups.unmute(groupId, 'zhouba');

时长为 1 到 315360000 秒（10 年）。本人是否被禁言在 group.self.muted 和 muted_until 中。

全员禁言

开启后只有群主和管理员可以发言，普通成员发送群消息时得到 group_muted（details.reason 为 all）。被单独禁言的管理员仍然不能发言。

await im.groups.setMuteAll(groupId, true);
await im.groups.setMuteAll(groupId, false);

群黑名单

被加入群黑名单的用户被移出群（如果在群里），之后不能再申请、被邀请或通过入群链接加入这个群。群主和管理员可以管理群黑名单；管理员只能移出由管理员加入的记录。每个群最多 1000 人。

await im.groups.blacklist.add(groupId, 'spammer', { reason: '发广告' });
const page = await im.groups.blacklist.list(groupId, { limit: 50 });
await im.groups.blacklist.remove(groupId, 'spammer');

列表的每项为 GroupBlacklistEntry。群黑名单只影响本群，与用户之间的黑名单无关。

公开群与入群申请

搜索公开群

im.groups.publicGroups() 按创建时间从新到旧列出公开群，可以按名称前缀搜索。每项只有公开的字段（group_id、type、name、avatar_url、description、member_count、join_mode、status），self 为本人在群里的信息，不是成员时为 null。

const page = await im.groups.publicGroups({ name_prefix: '摄影', limit: 20 });
render(page.items.map((g) => `${g.name}（${g.member_count} 人）${g.self ? ' 已加入' : ''}`));

申请加入

const { status } = await im.groups.applications.apply(groupId, { message: '我也喜欢摄影' });
if (status === 'joined') showToast('已加入');
else if (status === 'pending') showToast('已提交申请，等待群主或管理员审批');

群的申请方式为 free 时直接入群；为 approval 时产生一条待审批的申请，任意一位群主或管理员同意后入群。申请理由最长 256 个字符。申请被拒绝后 24 小时内不能再申请这个群（rate_limited，details.reason 为 declined_cooldown），同一个人对同一个群每天最多申请 5 次（pair_daily_limit）。私有群不能申请，得到 not_found；本人在群黑名单中得到 permission_denied（group_blacklisted）。

撤回待处理的申请，查看本人发出的申请：

await im.groups.applications.withdraw(groupId);
const mine = await im.groups.applications.mine();

申请已被处理时 withdraw 以 version_conflict 拒绝，details.status 为申请当前的状态。

审批申请和成员的邀请

群主和管理员用 im.groups.requests 查看和处理本群的请求。请求按“群 + 类型 + 用户名”定位，没有单独的 ID。请求的类型 kind：

`kind`	说明	由谁处理
`application`	用户申请加入公开群	群主或管理员
`invite_review`	普通成员在需要审批的群里发出的邀请	群主或管理员
`invitation`	等待被邀请人确认的邀请	被邀请人，见下一节

interface GroupRequest {
  group_id: string;
  kind: 'application' | 'invite_review' | 'invitation';
  username: string;
  nickname: string;
  message: string;
  status: 'pending' | 'accepted' | 'declined' | 'canceled' | 'expired';
}

const page = await im.groups.requests.list(groupId, { kind: 'application', status: 'pending' });
for (const r of page.items as GroupRequest[]) {
  render(`${r.nickname || r.username} 申请加入：${r.message}`);
}

const { result } = await im.groups.requests.approve(groupId, 'application', 'sunqi');
await im.groups.requests.decline(groupId, 'application', 'zhouba', { reason: '仅限本校学生' });

返回值的类型

requests.list()、applications.mine()、invitations.received()、blacklist.list()、joinLink 的几个方法和 settings.get() 的返回值在 TypeScript 中目前声明为 unknown。字段见本页的数据结构，可以像上例那样自己声明类型后断言。

approve 的 result：joined 已入群；invited 成员的邀请审批通过、被邀请人需要确认，已向他发出邀请；canceled 被邀请人已不能接收这个群的邀请，请求失效。
处理时会重新检查入群条件（群正常、不在群黑名单中、人数和群数未满），不满足时以对应的错误拒绝，请求保持待处理，条件满足后可以再次处理。
请求已被别人处理时以 version_conflict 拒绝，details.status 为请求当前的状态；已过期或不存在时以 not_found 拒绝。
拒绝的理由最长 256 个字符，展示给申请人或邀请人。拒绝申请后，申请人 24 小时内不能再申请。
普通成员调用 requests.list() 只能看到自己发出的邀请。邀请人、群主和管理员可以用 requests.withdrawInvite(group_id, kind, username) 撤回待处理的邀请（kind 为 invite_review 或 invitation）。

新的请求到达、请求被处理时发出 groupRequests.changed（list 为 pending，group_id 为这个群），可以据此刷新审批页面或显示红点。待处理的请求在最近一次发起后 7 天未处理即过期。完整规则见服务端的入群申请与邀请。

被邀请时是否需要确认

每个用户可以设置别人邀请自己入群时怎样处理：allow_any 直接入群，need_confirm 收到一条邀请、接受后才入群。没有设置过时使用应用运行策略中的默认值（默认 allow_any）。

const settings = (await im.groups.settings.get()) as { invite_mode: string | null; effective_invite_mode: string };
render(settings.effective_invite_mode);

await im.groups.settings.set('need_confirm');
await im.groups.settings.set(null);   // 清除本人的设置，改用应用的默认值

处理收到的邀请

interface GroupInvitation {
  group_id: string;
  inviter: { username: string; nickname: string; avatar_url: string } | null;
  message: string;
  status: string;
  group?: { group_id: string; name: string; avatar_url: string; member_count: number };
}

const page = await im.groups.invitations.received({ status: 'pending' });
for (const inv of page.items as GroupInvitation[]) {
  render(`${inv.inviter?.nickname ?? '有人'} 邀请你加入 ${inv.group?.name ?? '群聊'}`);
}

const group = await im.groups.invitations.accept('1840012345678901');
await im.groups.invitations.decline('1840099999999999', { reason: '暂时不参加' });

invitations.received() 和 applications.mine() 不带 cursor 和 status 时返回 SDK 内存中的第一页，不发请求；SDK 在登录、重连和收到相关通知时刷新这一页，刷新后发出 groupRequests.changed（list 为 invitations 或 applications）。
接受后入群，返回群信息，群随即出现在“我的群”中。本人已经通过其他途径入群的同样返回群信息。
拒绝后 24 小时内这个群不能再邀请本人。

入群链接

群主和管理员可以生成入群链接，私有群也可以。用户打开链接后确认即可直接入群，不需要审批。每个群同时只有一个有效链接，重新生成或撤销后旧链接立即失效；生成链接的人不再是群主或管理员时，链接也随之失效。链接可以展示为二维码。

interface JoinLink { link: string | null; expires_at: string | null; created_by: string | null }

const created = (await im.groups.joinLink.create(groupId, { expires_in_seconds: 86400 })) as JoinLink;
render(created.link);

const current = (await im.groups.joinLink.get(groupId)) as JoinLink;   // 没有有效链接时三项都为 null
await im.groups.joinLink.revoke(groupId);

有效期为 86400 到 604800 秒（1 到 7 天），默认 7 天。

打开链接的一方先预览，再确认加入：

interface JoinLinkPreview { group_id: string; name: string; avatar_url: string; member_count: number; is_member: boolean }

const preview = (await im.groups.joinLink.preview(link)) as JoinLinkPreview;
if (preview.is_member) {
  showToast('你已在群中');
} else {
  const group = await im.groups.joinLink.join(link);
  render(group.name);
}

链接无效、过期、已撤销，或群已封禁、已解散时，preview 和 join 都以 not_found 拒绝。已是成员时 join 直接返回群信息。预览和加入合计按用户每分钟 20 次限流。

退出与解散

await im.groups.leave(groupId);     // 退出群
await im.groups.dismiss(groupId);   // 解散群，只有群主可以

退出：退出后群从“我的群”中移除，本地的成员列表随之删除。群主退出以 owner_transfer_required 拒绝，请先转让群主；群里只剩群主一人时请解散。主动退出后 24 小时内，这个群不能再邀请本人。
解散：不能恢复。群的全部成员收到通知，群从各自的“我的群”中移除；群文件全部被删除。被平台封禁的群不能解散（group_disabled）。

被移出群或群被解散时，本人的群列表同样自动更新，原因可以从会话中的群提示消息得知（见消息）。

转让群主

群主可以把群主转让给群里的另一个成员。转让后原群主变为普通成员，原群主生成的入群链接失效。

const info = await im.groups.transferOwner(groupId, 'wangwu');
console.log(info.owner);   // wangwu

接口参考

各方法的 group_id 参数都是群 ID 字符串。私有群对非成员不可见，对它的任何操作都以 not_found 拒绝；本人不是公开群的成员时，只有成员才能做的操作以 not_group_member 拒绝；角色不够时以 permission_denied 拒绝；群被封禁时，被禁止的操作以 group_disabled 拒绝。下文不再逐个列出这几个错误。

im.groups.list()

返回本人加入的群的可订阅列表（LiveList<GroupView>），按群名排序；快照的 hasMore 总是 false。不再使用时调用 dispose()。未登录时抛出 not_signed_in。

im.groups.get()

读取一个群。

参数	类型	必填	说明
`group_id`	`string`	是	群 ID
`opts.refresh`	`boolean`	否	为 `true` 时不读本地，向服务端查询

返回值：Promise<GroupView | undefined>，看不到的群为 undefined。

im.groups.lookup()

批量查询群信息。

参数	类型	必填	说明
`group_ids`	`string[]`	是	1 到 100 个群 ID

返回值：Promise<GroupInfo[]>。看不到的群不在结果中；本人不是成员的公开群只有公开的字段。

可能的错误：local_validation（为空或超过 100 个）。

im.groups.publicGroups()

列出公开群，按创建时间从新到旧，不含已封禁和已解散的群。

参数	类型	必填	说明
`p.name_prefix`	`string`	否	按群名称的前缀搜索
`p.cursor`	`string \| null`	否	下一页的游标
`p.limit`	`number`	否	每页条数，默认 20，最大 100

返回值：Promise<Page<GroupInfo>>。

im.groups.create()

建群，本人为群主。不自动重试，见建群。

参数	类型	必填	说明
`p.type`	`'private' \| 'public'`	否	群类型，默认 `private`
`p.name`	`string`	否	群名称，最长 64 个字符
`p.avatar_url`	`string`	否	群头像地址
`p.description`	`string`	否	群简介，最长 512 个字符
`p.announcement`	`string`	否	群公告，最长 2048 个字符
`p.attributes`	`Record<string, string \| null> \| null`	否	自定义属性，全体成员可见；最多 32 项，合计不超过 4 KB
`p.member_invite`	`'free' \| 'approval' \| 'disabled'`	否	普通成员能否邀请他人，默认 `free`
`p.join_mode`	`'approval' \| 'free'`	否	公开群的申请方式，默认 `approval`；私有群不能设置
`p.members`	`string[]`	否	初始成员的用户名，最多 100 个
`p.message`	`string`	否	给初始成员的邀请附言

返回值：Promise<GroupInfo & { results: GroupMemberResult[] }>。

可能的错误：invalid_argument、permission_denied（应用关闭了客户端建群）、limit_exceeded（user_group_limit、app_group_limit）、content_rejected、rate_limited、app_unavailable（应用只读）、timeout。

im.groups.update()

修改群资料和设置（群主和管理员，群类型只有群主能改），只提交传入的字段。

参数	类型	必填	说明
`group_id`	`string`	是	群 ID
`patch`	同 `create` 的 `type` 到 `join_mode`	是	要修改的字段，至少一项。`attributes` 按项合并，值为 `null` 的键被删除，整个字段为 `null` 时清空
`patch.version`	`number`	否	读取到的 `info_version`，不一致时不修改

返回值：Promise<GroupInfo>，修改后的群信息。

可能的错误：invalid_argument（为私有群设置 join_mode 等）、content_rejected、version_conflict。

im.groups.transferOwner()

转让群主（群主）。

参数	类型	必填	说明
`group_id`	`string`	是	群 ID
`username`	`string`	是	新群主，必须是本群成员

返回值：Promise<GroupInfo>。

可能的错误：not_group_member（对方不是成员）。

im.groups.setMuteAll()

开启或关闭全员禁言（群主和管理员）。

参数	类型	必填	说明
`group_id`	`string`	是	群 ID
`on`	`boolean`	是	`true` 开启，`false` 关闭

返回值：Promise<GroupInfo>。

im.groups.leave()

退出群。

参数	类型	必填	说明
`group_id`	`string`	是	群 ID

返回值：Promise<void>。

可能的错误：owner_transfer_required（本人是群主）。

im.groups.dismiss()

解散群（群主），不能恢复。

参数	类型	必填	说明
`group_id`	`string`	是	群 ID

返回值：Promise<void>。

im.groups.onlineCount()

查询群的在线人数。同一个群 30 秒内重复调用返回上一次的结果。

参数	类型	必填	说明
`group_id`	`string`	是	群 ID

返回值：Promise<{ online_count: number; counted_at: string }>。

可能的错误：permission_denied（details.reason 为 presence_disabled：应用没有开启在线状态；presence_scope：在线状态的可见范围不是 all）、rate_limited。

im.groups.members()

返回群成员的可订阅列表（LiveList<GroupMember>）。只有成员可以查看。不再使用时调用 dispose()。

参数	类型	必填	说明
`group_id`	`string`	是	群 ID
`filter.role`	`GroupRole`	否	只列出这种角色的成员
`filter.muted`	`boolean`	否	`true` 只列出被禁言的成员，`false` 只列出没有被禁言的

获取失败时，快照的 error 为对应的 DRError。未登录时抛出 not_signed_in。

im.groups.lookupMembers()

按用户名查询成员信息（成员才能调用）。

参数	类型	必填	说明
`group_id`	`string`	是	群 ID
`usernames`	`string[]`	是	1 到 100 个用户名

返回值：Promise<GroupMember[]>，不是成员的用户不在结果中。

可能的错误：local_validation（为空或超过 100 个）。

im.groups.invite()

邀请他人入群。

参数	类型	必填	说明
`group_id`	`string`	是	群 ID
`usernames`	`string[]`	是	1 到 100 个用户名
`p.message`	`string`	否	邀请附言

返回值：Promise<GroupMemberResult[]>，每人的结果见邀请成员。

可能的错误：local_validation、permission_denied（普通成员在不允许邀请的群里邀请）、content_rejected（附言）。

im.groups.removeMembers()

移出成员（群主和管理员）。

参数	类型	必填	说明
`group_id`	`string`	是	群 ID
`usernames`	`string[]`	是	1 到 100 个用户名

返回值：Promise<GroupMemberResult[]>，成功的 status 为 removed 或 not_member。

可能的错误：local_validation、invalid_argument（移出自己）。

im.groups.updateMember()

修改成员的群昵称和成员属性：本人，或级别更高的群主、管理员。

参数	类型	必填	说明
`group_id`	`string`	是	群 ID
`username`	`string`	是	成员的用户名
`p.group_nickname`	`string`	否	群昵称，最长 64 个字符；空字符串表示清除
`p.attributes`	`Record<string, string \| null> \| null`	否	成员属性，按项合并；整个字段为 `null` 时清空。最多 16 项，合计不超过 1 KB

返回值：Promise<GroupMember>。

可能的错误：content_rejected（群昵称）、not_group_member（对方不是成员）。

im.groups.setRole()

设置或取消管理员（群主）。

参数	类型	必填	说明
`group_id`	`string`	是	群 ID
`username`	`string`	是	成员的用户名
`role`	`'admin' \| 'member'`	是	新角色

返回值：Promise<GroupMember>。

可能的错误：limit_exceeded（admin_limit）、invalid_argument（对群主设置）。

im.groups.mute()

禁言成员（群主和管理员）。

参数	类型	必填	说明
`group_id`	`string`	是	群 ID
`username`	`string`	是	成员的用户名
`p.duration_seconds`	`number`	否	禁言时长，1 到 315360000 秒；省略时永久禁言

返回值：Promise<GroupMember>。

im.groups.unmute()

解除成员的禁言（群主和管理员）。不能给自己解除。

参数	类型	必填	说明
`group_id`	`string`	是	群 ID
`username`	`string`	是	成员的用户名

返回值：Promise<GroupMember>。

im.groups.blacklist.list()

查询群黑名单（群主和管理员）。

参数	类型	必填	说明
`group_id`	`string`	是	群 ID
`page.cursor`	`string \| null`	否	下一页的游标
`page.limit`	`number`	否	每页条数，默认 20，最大 100

返回值：Promise<Page<unknown>>，每项为 GroupBlacklistEntry。

im.groups.blacklist.add()

把用户加入群黑名单（群主和管理员）；他在群里时同时被移出。已在群黑名单中时同样成功。

参数	类型	必填	说明
`group_id`	`string`	是	群 ID
`username`	`string`	是	用户名
`p.reason`	`string`	否	原因

返回值：Promise<void>。

可能的错误：limit_exceeded（group_blacklist_limit）、invalid_argument（拉黑自己）。

im.groups.blacklist.remove()

把用户移出群黑名单。管理员只能移出由管理员加入的记录。

参数	类型	必填	说明
`group_id`	`string`	是	群 ID
`username`	`string`	是	用户名

返回值：Promise<void>。

im.groups.joinLink.get()

查询当前有效的入群链接（群主和管理员）。

参数	类型	必填	说明
`group_id`	`string`	是	群 ID

返回值：Promise<unknown>，为 JoinLink；没有有效链接时三个字段都为 null。

im.groups.joinLink.create()

生成或重新生成入群链接（群主和管理员），旧链接立即失效。

参数	类型	必填	说明
`group_id`	`string`	是	群 ID
`p.expires_in_seconds`	`number`	否	有效期，86400 到 604800 秒，默认 604800

返回值：Promise<unknown>，为 JoinLink。

im.groups.joinLink.revoke()

撤销入群链接（群主和管理员）。

参数	类型	必填	说明
`group_id`	`string`	是	群 ID

返回值：Promise<void>。

im.groups.joinLink.preview()

预览入群链接。

参数	类型	必填	说明
`link`	`string`	是	入群链接

返回值：Promise<unknown>，为 JoinLinkPreview。

可能的错误：not_found（链接无效、过期、已撤销，或群已封禁、已解散）、rate_limited。

im.groups.joinLink.join()

通过入群链接加入。已是成员时直接返回群信息。

参数	类型	必填	说明
`link`	`string`	是	入群链接

返回值：Promise<GroupInfo>。

可能的错误：not_found、permission_denied（在群黑名单中，或被加群前回调拒绝）、limit_exceeded（群已满或本人的群数已满）、rate_limited。

im.groups.applications.apply()

申请加入公开群。

参数	类型	必填	说明
`group_id`	`string`	是	群 ID
`p.message`	`string`	否	申请理由，最长 256 个字符

返回值：Promise<{ status: 'joined' | 'pending' | 'already_member' }>。

可能的错误：not_found（私有群）、permission_denied（group_blacklisted，或被加群前回调拒绝）、limit_exceeded（user_group_limit、group_member_limit）、rate_limited（declined_cooldown、pair_daily_limit、request_rate、group_join_rate）、content_rejected。

im.groups.applications.withdraw()

撤回本人待处理的申请。已撤回过同样成功。

参数	类型	必填	说明
`group_id`	`string`	是	群 ID

返回值：Promise<void>。

可能的错误：version_conflict（申请已被处理，details.status 为当前状态）。

im.groups.applications.mine()

查询本人发出的入群申请，按发起时间从新到旧。

参数	类型	必填	说明
`p.status`	`string`	否	只列出这种状态的申请
`p.cursor`	`string \| null`	否	下一页的游标
`p.limit`	`number`	否	每页条数

返回值：Promise<Page<unknown>>，每项为 GroupRequest。不带 cursor 和 status 时返回 SDK 内存中的第一页。

im.groups.invitations.received()

查询本人收到的入群邀请，按发起时间从新到旧。参数同 applications.mine()。

返回值：Promise<Page<unknown>>，每项为 GroupRequest。不带 cursor 和 status 时返回 SDK 内存中的第一页。

im.groups.invitations.accept()

接受入群邀请。

参数	类型	必填	说明
`group_id`	`string`	是	群 ID

返回值：Promise<GroupInfo>。

可能的错误：not_found（邀请不存在或已过期）、permission_denied（在群黑名单中）、limit_exceeded、rate_limited（group_join_rate）、version_conflict（邀请已被撤回等）。

im.groups.invitations.decline()

拒绝入群邀请，之后 24 小时内这个群不能再邀请本人。

参数	类型	必填	说明
`group_id`	`string`	是	群 ID
`p.reason`	`string`	否	拒绝理由，最长 256 个字符

返回值：Promise<void>。

im.groups.requests.list()

查询本群的请求，按发起时间从新到旧。群主和管理员可以看到全部类型，普通成员只能看到自己发出的邀请。

参数	类型	必填	说明
`group_id`	`string`	是	群 ID
`p.kind`	`string`	否	`application`、`invite_review` 或 `invitation`
`p.status`	`string`	否	`pending`、`accepted`、`declined`、`canceled` 或 `expired`
`p.cursor`	`string \| null`	否	下一页的游标
`p.limit`	`number`	否	每页条数

返回值：Promise<Page<unknown>>，每项为 GroupRequest。每次都向服务端查询。

im.groups.requests.approve()

通过申请或成员发起的邀请（群主和管理员）。

参数	类型	必填	说明
`group_id`	`string`	是	群 ID
`kind`	`string`	是	`application` 或 `invite_review`
`username`	`string`	是	申请人或被邀请人

返回值：Promise<{ result: 'joined' | 'invited' | 'canceled' }>。

可能的错误：not_found（请求不存在或已过期）、version_conflict（已被别人处理）、permission_denied（group_blacklisted）、limit_exceeded、rate_limited（group_join_rate）。

im.groups.requests.decline()

拒绝申请或成员发起的邀请（群主和管理员）。

参数	类型	必填	说明
`group_id`	`string`	是	群 ID
`kind`	`string`	是	`application` 或 `invite_review`
`username`	`string`	是	申请人或被邀请人
`p.reason`	`string`	否	拒绝理由，最长 256 个字符

返回值：Promise<void>。

可能的错误：not_found、version_conflict、content_rejected（理由）。

im.groups.requests.withdrawInvite()

撤回待处理的邀请：邀请人本人，或群主、管理员。

参数	类型	必填	说明
`group_id`	`string`	是	群 ID
`kind`	`'invite_review' \| 'invitation'`	是	请求的类型
`username`	`string`	是	被邀请人

返回值：Promise<void>。

可能的错误：not_found、version_conflict。

im.groups.settings.get()

查询本人被邀请时的处理方式。

返回值：Promise<unknown>，为 { invite_mode: 'allow_any' | 'need_confirm' | null; effective_invite_mode: 'allow_any' | 'need_confirm' }。invite_mode 为本人的设置，没有设置过时为 null。

im.groups.settings.set()

设置本人被邀请时的处理方式。

参数	类型	必填	说明
`mode`	`string \| null`	是	`allow_any` 或 `need_confirm`；`null` 清除设置，改用应用的默认值

返回值：Promise<void>。

事件	载荷	说明
`groups.changed`	`{ upserted: string[]; removed: string[] }`	群信息变化（`upserted`），或群离开了“我的群”（`removed`）
`groupMembers.changed`	`{ group_id: string; usernames: string[] \| null }`	本地保存的成员列表变化；`usernames` 为 `null` 表示整体变化
`groupRequests.changed`	`{ list: 'pending' \| 'invitations' \| 'applications'; group_id: string \| null }`	`pending`：这个群的待审批请求有变化；`invitations`、`applications`：本人收到的邀请、发出的申请的第一页已刷新

数据结构

GroupView

字段	类型	说明
`group_id`	`string`	群 ID
`group`	`GroupInfo`	群信息；已离开的群为离开前最后一次的信息
`in_my_groups`	`boolean`	是否在“我的群”中

GroupInfo

本人是成员时有全部字段；本人不是成员的公开群只有 group_id、type、name、avatar_url、description、member_count、join_mode、status 和 self。

字段	类型	说明
`group_id`	`string`	群 ID
`type`	`'private' \| 'public'`	群类型
`name`	`string`	群名称，没有时为空字符串
`avatar_url`	`string`	群头像地址，没有时为空字符串
`description`	`string`	群简介
`announcement`	`string`	群公告
`announcement_updated_at`	`string \| null`	公告最近一次修改的时间
`announcement_updated_by`	`string \| null`	最近一次在客户端修改公告的用户名
`attributes`	`Record<string, string> \| null`	自定义属性
`owner`	`string`	群主的用户名
`member_invite`	`string`	普通成员能否邀请他人：`free`、`approval`、`disabled`
`join_mode`	`string \| null`	公开群的申请方式：`approval`、`free`；私有群为 `null`
`mute_all`	`boolean`	是否开启了全员禁言
`max_members`	`number`	人数上限
`member_count`	`number`	当前人数，含群主
`status`	`string`	`active` 正常、`disabled` 已封禁、`dismissed` 已解散
`disabled_by`	`string \| null`	封禁方：`tenant` 应用、`platform` 平台；未封禁时为 `null`
`info_version`	`number`	群资料和设置的版本号，可用于 `update` 的 `version`
`member_version`	`number`	成员列表的版本号
`created_at`	`string`	创建时间
`self`	`object \| null`	本人在群里的信息：`role`、`group_nickname`、`muted`、`muted_until`、`joined_at`；不是成员时为 `null`

GroupMember

字段	类型	说明
`username`	`string`	用户名
`nickname`	`string`	用户资料中的昵称
`avatar_url`	`string`	用户资料中的头像
`role`	`GroupRole`	`owner`、`admin` 或 `member`
`group_nickname`	`string`	本群的群昵称，没有时为空字符串
`attributes`	`Record<string, string> \| null`	成员属性
`muted`	`boolean`	是否被禁言
`muted_until`	`string \| null`	禁言的到期时间，永久禁言为 `null`
`joined_via`	`string`	入群方式：`create` 建群时、`server` 服务端添加、`invite` 被邀请、`apply` 申请、`link` 入群链接
`inviter`	`string \| null`	邀请人的用户名
`joined_at`	`string`	入群时间

GroupMemberResult

批量操作中一个用户的结果，二者之一：

形式	说明
`{ username, status }`	成功。`status` 为 `joined`、`invited`、`pending_review`、`already_member`（邀请、建群），或 `removed`、`not_member`（移出）
`{ username, code, message?, details? }`	失败。`code` 为错误码，`details.reason` 说明原因

GroupRole

'owner' | 'admin' | 'member'。

GroupRequest

入群申请或邀请，requests.list()、applications.mine()、invitations.received() 的每项。

字段	类型	说明
`group_id`	`string`	群 ID
`kind`	`string`	`application`、`invite_review` 或 `invitation`
`username`	`string`	请求的目标用户：申请人或被邀请人
`nickname`	`string`	目标用户的昵称
`avatar_url`	`string`	目标用户的头像
`inviter`	`object \| null`	邀请人的 `username`、`nickname`、`avatar_url`；申请为 `null`
`message`	`string`	申请理由或邀请附言
`reason`	`string`	拒绝理由
`status`	`string`	`pending`、`accepted`、`declined`、`canceled` 或 `expired`
`cancel_cause`	`string \| null`	失效的原因：`withdrawn`、`joined`、`blacklisted`、`group_private`、`not_eligible`、`dismissed`
`requested_at`	`string`	最近一次发起的时间
`expires_at`	`string \| null`	过期时间，只有待处理的有值
`handled_at`	`string \| null`	处理时间
`handled_by`	`string \| null`	处理人的用户名
`group`	`object`	只在本人收到的邀请和发出的申请中：群的 `group_id`、`name`、`avatar_url`、`member_count`。群是私有群且请求已处理时没有这一项

群被封禁期间，待处理的请求显示为 canceled、cancel_cause 为 null，解封后恢复。

GroupBlacklistEntry

字段	类型	说明
`username`	`string`	用户名
`nickname`	`string`	昵称
`avatar_url`	`string`	头像
`reason`	`string`	原因
`created_by`	`string \| null`	执行操作的群主或管理员
`created_by_role`	`string`	加入时操作人的身份：`owner`、`admin` 或 `server`
`created_at`	`string`	加入的时间

JoinLink

字段	类型	说明
`link`	`string \| null`	入群链接
`expires_at`	`string \| null`	过期时间
`created_by`	`string \| null`	生成链接的人

JoinLinkPreview

字段	类型	说明
`group_id`	`string`	群 ID
`name`	`string`	群名称
`avatar_url`	`string`	群头像
`member_count`	`number`	人数
`is_member`	`boolean`	本人是否已是成员

群组 ​

基本概念 ​

群类型 ​

角色与权限 ​

群设置 ​

建群 ​

我的群 ​

修改群资料和设置 ​

设置群头像 ​

成员列表 ​

邀请成员 ​

移出成员 ​

设置管理员 ​

群昵称与成员属性 ​

禁言 ​

禁言成员 ​

全员禁言 ​

群黑名单 ​

公开群与入群申请 ​

搜索公开群 ​

申请加入 ​

审批申请和成员的邀请 ​

被邀请时是否需要确认 ​

处理收到的邀请 ​

入群链接 ​

退出与解散 ​

转让群主 ​

接口参考 ​

im.groups.list() ​

im.groups.get() ​

im.groups.lookup() ​

im.groups.publicGroups() ​

im.groups.create() ​

im.groups.update() ​

im.groups.transferOwner() ​

im.groups.setMuteAll() ​

im.groups.leave() ​

im.groups.dismiss() ​

im.groups.onlineCount() ​

im.groups.members() ​

im.groups.lookupMembers() ​

im.groups.invite() ​

im.groups.removeMembers() ​

im.groups.updateMember() ​

im.groups.setRole() ​

im.groups.mute() ​

im.groups.unmute() ​

im.groups.blacklist.list() ​

im.groups.blacklist.add() ​

im.groups.blacklist.remove() ​

im.groups.joinLink.get() ​

im.groups.joinLink.create() ​

im.groups.joinLink.revoke() ​

im.groups.joinLink.preview() ​

im.groups.joinLink.join() ​

im.groups.applications.apply() ​

im.groups.applications.withdraw() ​

im.groups.applications.mine() ​

im.groups.invitations.received() ​

im.groups.invitations.accept() ​

im.groups.invitations.decline() ​

im.groups.requests.list() ​

im.groups.requests.approve() ​

im.groups.requests.decline() ​

im.groups.requests.withdrawInvite() ​

im.groups.settings.get() ​

im.groups.settings.set() ​

相关事件 ​

数据结构 ​

GroupView ​

GroupInfo ​

GroupMember ​

GroupMemberResult ​

GroupRole ​

GroupRequest ​

GroupBlacklistEntry ​

JoinLink ​

JoinLinkPreview ​

群组

基本概念

群类型

角色与权限

群设置

建群

我的群

修改群资料和设置

设置群头像

成员列表

邀请成员

移出成员

设置管理员

群昵称与成员属性

禁言

禁言成员

全员禁言

群黑名单

公开群与入群申请

搜索公开群

申请加入

审批申请和成员的邀请

被邀请时是否需要确认

处理收到的邀请

入群链接

退出与解散

转让群主

接口参考

im.groups.list()

im.groups.get()

im.groups.lookup()

im.groups.publicGroups()

im.groups.create()

im.groups.update()

im.groups.transferOwner()

im.groups.setMuteAll()

im.groups.leave()

im.groups.dismiss()

im.groups.onlineCount()

im.groups.members()

im.groups.lookupMembers()

im.groups.invite()

im.groups.removeMembers()

im.groups.updateMember()

im.groups.setRole()

im.groups.mute()

im.groups.unmute()

im.groups.blacklist.list()

im.groups.blacklist.add()

im.groups.blacklist.remove()

im.groups.joinLink.get()

im.groups.joinLink.create()

im.groups.joinLink.revoke()

im.groups.joinLink.preview()

im.groups.joinLink.join()

im.groups.applications.apply()

im.groups.applications.withdraw()

im.groups.applications.mine()

im.groups.invitations.received()

im.groups.invitations.accept()

im.groups.invitations.decline()

im.groups.requests.list()

im.groups.requests.approve()

im.groups.requests.decline()

im.groups.requests.withdrawInvite()

im.groups.settings.get()

im.groups.settings.set()

相关事件

数据结构

GroupView

GroupInfo

GroupMember

GroupMemberResult

GroupRole

GroupRequest

GroupBlacklistEntry

JoinLink

JoinLinkPreview