Class Group

绑定固定 groupId 的单群上下文对象。

Constructors

constructor

Properties

groupId

Methods

getSummary getDetail refresh updateInfo updateConfigs changeOwner destroy leave getMembers removeMembers getAdmins addAdmin removeAdmin getMuteList muteMembers unmuteMembers muteAllMembers unmuteAllMembers getBlocklist blockMembers unblockMembers getAllowlist addUsersToAllowlist removeUsersFromAllowlist checkIfInAllowList checkIfInMuteList getAnnouncement updateAnnouncement getSharedFileList uploadSharedFile deleteSharedFile downloadSharedFile setMemberAttributes getMembersAttributes

Constructors

constructor

Properties

ReadonlygroupId

groupId: string

Methods

getSummary

  • getSummary(): null | JoinedGroupSummary

    读取当前会话或本地预览中已知的已加入群轻量摘要。该方法不会发起网络请求，返回结果也不等同于完整群组详情。

    Returns null | JoinedGroupSummary

    返回本地已知的群组轻量摘要；如果当前没有可用摘要，则返回 null。

    Example: 读取本地轻量摘要。

    const group = client.groupManager.getGroup('group-1');
    const summary = group.getSummary();

getDetail

  • getDetail(): Promise<GroupDetail>

    获取当前群组详情。该方法会优先复用当前会话中的可用快照，必要时再从服务端拉取最新数据。

    Returns Promise<GroupDetail>

    返回标准化群组详情。

    Example: 获取群详情

    const group = client.groupManager.getGroup('group-1');
    const detail = await group.getDetail();

    可能出现的错误码

    Code 含义 HTTP 处理建议 可重试
    606 群组不存在 404 确认 groupId 正确且群组仍存在 否

refresh

  • refresh(): Promise<GroupDetail>

    强制从服务端拉取并刷新当前群组详情。

    Returns Promise<GroupDetail>

    返回刷新后的标准化群组详情。

    Example: 刷新群详情

    const detail = await client.groupManager.getGroup('group-1').refresh();

    可能出现的错误码

    Code 含义 HTTP 处理建议 可重试
    606 群组不存在 404 确认 groupId 正确且群组仍存在 否

updateInfo

  • updateInfo(input: GroupUpdateInfoInput): Promise<void>

    更新当前群组的基础资料，例如群组名称、群组描述、头像或扩展信息。

    Parameters

    Returns Promise<void>

    更新成功后无返回值。

    Example: 更新群名称

    await client.groupManager.getGroup('group-1').updateInfo({ name: 'New group name' });

    可能出现的错误码

    Code 含义 HTTP 处理建议 可重试
    603 无权限的群组操作 403 使用群主或管理员账号重试 否
    603 无权限的群组操作 403 确认当前用户权限与群组状态满足更新要求 否
    110 参数无效：群组字段不支持修改 400 仅提交允许修改的字段，并确保字段长度合法 否
    110 参数无效：群组字段长度超限 403 缩短本次提交的群组字段内容后重试 否
    608 群组名称无效 403 更换为合法群组名称后重试 否
    606 群组不存在 404 确认 groupId 正确且群组仍存在 否
    607 群组已禁用 403 先恢复群组可用状态，再重试该操作 否

updateConfigs

  • updateConfigs(input: GroupUpdateConfigsInput): Promise<void>

    更新当前群组的配置，例如是否公开、入群审批方式、普通成员邀请权限以及群成员人数上限。

    Parameters

    Returns Promise<void>

    更新成功后无返回值。

    Example: 关闭成员邀请

    await client.groupManager.getGroup('group-1').updateConfigs({ allowInvites: false });

    可能出现的错误码

    Code 含义 HTTP 处理建议 可重试
    603 无权限的群组操作 403 使用群主或管理员账号重试 否
    603 无权限的群组操作 403 确认当前用户权限与群组状态满足更新要求 否
    110 参数无效：群组字段不支持修改 400 仅提交允许修改的字段，并确保字段长度合法 否
    110 参数无效：群组字段长度超限 403 缩短本次提交的群组字段内容后重试 否
    608 群组名称无效 403 更换为合法群组名称后重试 否
    606 群组不存在 404 确认 groupId 正确且群组仍存在 否
    607 群组已禁用 403 先恢复群组可用状态，再重试该操作 否

changeOwner

  • changeOwner(input: GroupOwnerChangeInput): Promise<void>

    转让当前群组的所有权。

    Parameters

    Returns Promise<void>

    转让成功后无返回值。

    Example: 转让群主

    await client.groupManager.getGroup('group-1').changeOwner({ newOwner: 'user-2' });

    可能出现的错误码

    Code 含义 HTTP 处理建议 可重试
    603 无权限的群组操作 403 传入有效的新群主成员 ID，并使用当前群主账号重试 否
    606 群组不存在 404 确认 groupId 正确且群组仍存在 否

destroy

  • destroy(): Promise<void>

    解散当前群组。

    Returns Promise<void>

    解散成功后无返回值。

    Example: 解散群组

    await client.groupManager.getGroup('group-1').destroy();

    可能出现的错误码

    Code 含义 HTTP 处理建议 可重试
    603 无权限的群组操作 403 使用群主账号重试 否
    606 群组不存在 404 确认 groupId 正确且群组仍存在 否
    607 群组已禁用 403 确认群组状态后再重试 否

leave

  • leave(): Promise<void>

    当前登录用户主动退出群组。

    Returns Promise<void>

    退出成功后无返回值。

    Example: 退出群组

    await client.groupManager.getGroup('group-1').leave();

    可能出现的错误码

    Code 含义 HTTP 处理建议 可重试
    602 用户未加入该群组 - 确认当前用户已加入目标群组 否
    603 群主不能退出群组 403 先调用 changeGroupOwner 转让群主，再退出群组 否
    606 群组不存在 404 确认 groupId 正确且群组仍存在 否

getMembers

  • getMembers(query?: CursorPageParams): Promise<GroupMemberListResult>

    分页获取当前群组的成员列表。

    Parameters

    Returns Promise<GroupMemberListResult>

    返回群成员分页结果。

    Example: 获取群成员

    const page = await client.groupManager.getGroup('group-1').getMembers({ pageSize: 20 });

    可能出现的错误码

    Code 含义 HTTP 处理建议 可重试
    606 群组不存在 404 确认 groupId 正确且群组仍存在 否

removeMembers

  • removeMembers(input: GroupUserBatchInput): Promise<void>

    从当前群组中移除指定成员。

    Parameters

    Returns Promise<void>

    移除成功后无返回值。

    Example: 移除群成员

    await client.groupManager.getGroup('group-1').removeMembers({ userIds: ['user-2'] });

    Throws

    错误码 110：成员列表为空、成员用户 ID 不合法，或目标群组不存在。

    Throws

    错误码 202：鉴权失败，或当前用户无权限移除群成员。

getAdmins

  • getAdmins(): Promise<readonly GroupUserInfo[]>

    获取当前群组的管理员列表。

    Returns Promise<readonly GroupUserInfo[]>

    返回管理员的群上下文用户资料列表。

    Example: 获取管理员

    const admins = await client.groupManager.getGroup('group-1').getAdmins();

    可能出现的错误码

    Code 含义 HTTP 处理建议 可重试
    606 群组不存在 404 确认 groupId 正确且群组仍存在 否

addAdmin

  • addAdmin(input: { userId: string }): Promise<void>

    添加群组管理员。

    Parameters

    • input: { userId: string }

      待设为管理员的用户 ID。

    Returns Promise<void>

    设置成功后无返回值。

    Example: 添加管理员

    await client.groupManager.getGroup('group-1').addAdmin({ userId: 'user-2' });

    Throws

    错误码 110：用户 ID 不合法、目标用户不在群组中，或目标群组不存在。

    Throws

    错误码 202：鉴权失败，或当前用户无权限添加管理员。

removeAdmin

  • removeAdmin(input: { userId: string }): Promise<void>

    移除群管理员。

    Parameters

    • input: { userId: string }

      待移除管理员权限的用户 ID。

    Returns Promise<void>

    移除成功后无返回值。

    Example: 移除管理员

    await client.groupManager.getGroup('group-1').removeAdmin({ userId: 'user-2' });

    Throws

    错误码 110：用户 ID 不合法、目标用户不是管理员，或目标群组不存在。

    Throws

    错误码 202：鉴权失败，或当前用户无权限移除管理员。

getMuteList

  • getMuteList(page?: NumberPageParams): Promise<readonly GroupMuteEntry[]>

    获取当前群组的禁言列表。

    Parameters

    Returns Promise<readonly GroupMuteEntry[]>

    返回禁言成员列表。

    Example: 获取禁言列表

    const mutes = await client.groupManager.getGroup('group-1').getMuteList({ pageSize: 20 });

    可能出现的错误码

    Code 含义 HTTP 处理建议 可重试
    606 群组不存在 404 确认 groupId 正确且群组仍存在 否

muteMembers

  • muteMembers(input: GroupMuteMembersInput): Promise<void>

    将当前群组中的指定成员加入禁言列表。

    Parameters

    • input: GroupMuteMembersInput

      待禁言成员的用户 ID 列表，以及禁言时长（单位：毫秒）。

    Returns Promise<void>

    禁言成功后无返回值。

    Example: 禁言成员

    await client.groupManager.getGroup('group-1').muteMembers({
      userIds: ['user-2'],
      muteDuration: 3_600_000,
    });

    Throws

    错误码 110：成员列表为空、成员用户 ID 不合法，或禁言时长不合法。

    Throws

    错误码 202：鉴权失败，或当前用户无权限禁言成员。

unmuteMembers

  • unmuteMembers(input: GroupUserBatchInput): Promise<void>

    解除当前群组中指定成员的禁言状态。

    Parameters

    Returns Promise<void>

    解除成功后无返回值。

    Example: 解除禁言

    await client.groupManager.getGroup('group-1').unmuteMembers({ userIds: ['user-2'] });

    Throws

    错误码 110：成员列表为空，或成员用户 ID 不合法。

    Throws

    错误码 202：鉴权失败，或当前用户无权限解除禁言。

muteAllMembers

  • muteAllMembers(): Promise<void>

    开启当前群组的全员禁言。

    Returns Promise<void>

    开启成功后无返回值。

    Example: 开启全员禁言

    await client.groupManager.getGroup('group-1').muteAllMembers();

    Throws

    错误码 110：群组 ID 不合法，或目标群组不存在。

    Throws

    错误码 202：鉴权失败，或当前用户无权限开启全员禁言。

unmuteAllMembers

  • unmuteAllMembers(): Promise<void>

    关闭当前群组的全员禁言。

    Returns Promise<void>

    关闭成功后无返回值。

    Example: 关闭全员禁言

    await client.groupManager.getGroup('group-1').unmuteAllMembers();

    Throws

    错误码 110：群组 ID 不合法，或目标群组不存在。

    Throws

    错误码 202：鉴权失败，或当前用户无权限关闭全员禁言。

getBlocklist

  • getBlocklist(page?: NumberPageParams): Promise<readonly GroupBlocklistEntry[]>

    获取当前群组的黑名单列表。

    Parameters

    Returns Promise<readonly GroupBlocklistEntry[]>

    返回黑名单成员列表。

    Example: 获取群黑名单。

    const blocklist = await client.groupManager.getGroup('group-1').getBlocklist({ pageSize: 20 });

    可能出现的错误码

    Code 含义 HTTP 处理建议 可重试
    606 群组不存在 404 确认 groupId 正确且群组仍存在 否

blockMembers

  • blockMembers(input: GroupUserBatchInput): Promise<void>

    将指定成员加入当前群组的黑名单。

    Parameters

    Returns Promise<void>

    加入成功后无返回值。

    Example: 加入黑名单。

    await client.groupManager.getGroup('group-1').blockMembers({ userIds: ['user-2'] });

    Throws

    错误码 110：成员列表为空、成员用户 ID 不合法，或目标群组不存在。

    Throws

    错误码 202：鉴权失败，或当前用户无权限操作黑名单。

unblockMembers

  • unblockMembers(input: GroupUserBatchInput): Promise<void>

    将指定成员移出当前群组的黑名单。

    Parameters

    Returns Promise<void>

    移出成功后无返回值。

    Example: 移出黑名单。

    await client.groupManager.getGroup('group-1').unblockMembers({ userIds: ['user-2'] });

    Throws

    错误码 110：成员列表为空，或成员用户 ID 不合法。

    Throws

    错误码 202：鉴权失败，或当前用户无权限操作黑名单。

getAllowlist

  • getAllowlist(): Promise<readonly GroupAllowlistEntry[]>

    获取当前群组的白名单列表。

    Returns Promise<readonly GroupAllowlistEntry[]>

    返回白名单成员列表。

    Example: 获取白名单。

    const allowlist = await client.groupManager.getGroup('group-1').getAllowlist();

    可能出现的错误码

    Code 含义 HTTP 处理建议 可重试
    606 群组不存在 404 确认 groupId 正确且群组仍存在 否

addUsersToAllowlist

  • addUsersToAllowlist(input: GroupUserBatchInput): Promise<void>

    将指定成员加入当前群组的白名单。

    Parameters

    Returns Promise<void>

    加入成功后无返回值。

    Example: 加入白名单。

    await client.groupManager.getGroup('group-1').addUsersToAllowlist({ userIds: ['user-2'] });

    Throws

    错误码 110：成员列表为空、成员用户 ID 不合法，或目标群组不存在。

    Throws

    错误码 202：鉴权失败，或当前用户无权限操作白名单。使用具备权限的账号重试，并确认鉴权状态有效。

removeUsersFromAllowlist

  • removeUsersFromAllowlist(input: GroupUserBatchInput): Promise<void>

    将指定成员移出当前群组的白名单。

    Parameters

    Returns Promise<void>

    移出成功后无返回值。

    Example: 移出白名单。

    await client.groupManager.getGroup('group-1').removeUsersFromAllowlist({ userIds: ['user-2'] });

    Throws

    错误码 110：成员列表为空，或成员用户 ID 不合法。

    Throws

    错误码 202：鉴权失败，或当前用户无权限操作白名单。

checkIfInAllowList

  • checkIfInAllowList(): Promise<boolean>

    查询当前用户是否在当前群组的白名单中。

    Returns Promise<boolean>

    如果当前登录用户在白名单中，则返回 true；否则返回 false。

    Example: 查询是否在白名单

    const inAllowlist = await client.groupManager.getGroup('group-1').checkIfInAllowList();

    Throws

    错误码 110：群组 ID 不合法，或目标群组不存在。

    Throws

    错误码 202：鉴权失败。重新登录或刷新鉴权信息后重试。

checkIfInMuteList

  • checkIfInMuteList(): Promise<boolean>

    查询当前用户是否在当前群组的禁言列表中。

    Returns Promise<boolean>

    如果当前登录用户在禁言列表中，则返回 true；否则返回 false。

    Example: 查询是否被禁言

    const muted = await client.groupManager.getGroup('group-1').checkIfInMuteList();

    可能出现的错误码

    Code 含义 HTTP 处理建议 可重试
    606 群组不存在 404 确认 groupId 正确且群组仍存在 否

getAnnouncement

  • getAnnouncement(): Promise<GroupAnnouncement>

    获取当前群组公告。

    Returns Promise<GroupAnnouncement>

    返回群公告对象。

    Example: 获取群公告

    const announcement = await client.groupManager.getGroup('group-1').getAnnouncement();

    可能出现的错误码

    Code 含义 HTTP 处理建议 可重试
    606 群组不存在 404 确认 groupId 正确且群组仍存在 否

updateAnnouncement

  • updateAnnouncement(input: GroupAnnouncementUpdateInput): Promise<void>

    更新当前群组公告。

    Parameters

    Returns Promise<void>

    更新成功后无返回值。

    Example: 更新群公告

    await client.groupManager.getGroup('group-1').updateAnnouncement({ announcement: 'Welcome' });

    可能出现的错误码

    Code 含义 HTTP 处理建议 可重试
    110 参数无效：群公告长度超限 403 缩短公告内容后重试 否
    110 参数无效：群公告长度超限 403 缩短公告内容后重试 否

getSharedFileList

  • getSharedFileList(query?: NumberPageParams): Promise<GroupSharedFileListResult>

    分页获取当前群组的共享文件列表。

    Parameters

    Returns Promise<GroupSharedFileListResult>

    返回共享文件分页结果。

    Example: 获取共享文件

    const files = await client.groupManager.getGroup('group-1').getSharedFileList({ pageSize: 20 });

    可能出现的错误码

    Code 含义 HTTP 处理建议 可重试
    606 群组不存在 404 确认 groupId 正确且群组仍存在 否

uploadSharedFile

  • uploadSharedFile(input: GroupUploadSharedFileInput): Promise<void>

    上传文件到当前群组的共享文件列表中。

    Parameters

    Returns Promise<void>

    上传成功后无返回值。

    Example: 上传共享文件

    await client.groupManager.getGroup('group-1').uploadSharedFile({
      file,
      onFileUploadProgress: event => console.log(event.loaded),
    });

    Throws

    错误码 110：群组 ID 或文件参数不合法。

    Throws

    错误码 202：鉴权失败，或当前用户无权限上传共享文件。

    Throws

    错误码 1：上传被取消，或当前平台上传失败。检查上传环境和网络状态后重试。

deleteSharedFile

  • deleteSharedFile(input: GroupDeleteSharedFileInput): Promise<void>

    删除当前群组中的共享文件。

    Parameters

    Returns Promise<void>

    删除成功后无返回值。

    Example: 删除共享文件

    await client.groupManager.getGroup('group-1').deleteSharedFile({ fileId: 'file-1' });

    可能出现的错误码

    Code 含义 HTTP 处理建议 可重试
    603 无权限的群组操作 - 使用群主、管理员或文件所有者账号重试 否
    605 群共享文件 ID 无效 - 确认 fileId 正确且共享文件仍存在 否
    606 群组不存在 - 确认 groupId 正确且群组仍存在 否

downloadSharedFile

  • downloadSharedFile(input: GroupDownloadSharedFileInput): Promise<void>

    下载当前群组中的共享文件。下载完成后，会通过回调返回 Blob 数据。

    Parameters

    Returns Promise<void>

    下载流程完成时 resolve。

    Example: 下载共享文件

    await client.groupManager.getGroup('group-1').downloadSharedFile({
      fileId: 'file-1',
      onFileDownloadComplete: blob => console.log(blob.size),
    });

    Throws

    错误码 110：群组 ID 或文件 ID 不合法。

    Throws

    错误码 202：鉴权失败。重新登录或刷新鉴权信息后重试。

    Throws

    错误码 303：HTTP 下载失败。检查网络状态和文件资源后重试。

setMemberAttributes

  • setMemberAttributes(input: GroupSetMemberAttributesInput): Promise<void>

    设置当前群组中指定成员的自定义属性，常用于设置群成员名片。

    Parameters

    Returns Promise<void>

    设置成功后无返回值。

    Example: 设置群名片

    await client.groupManager.getGroup('group-1').setMemberAttributes({
      userId: 'user-1',
      memberAttributes: { groupNamecard: 'Alice' },
    });

    可能出现的错误码

    Code 含义 HTTP 处理建议 可重试
    609 群组成员属性个数超上限 - 减少成员属性条目数量后重试 否
    610 群组成员属性更新失败 - 检查属性内容与当前群成员状态后重试 否
    611 群组成员属性 key 长度超上限 - 缩短属性 key 后重试 否
    612 群组成员属性 value 长度超上限 - 缩短属性 value 后重试 否
    602 用户未加入该群组 404 确认目标用户已加入群组 否
    210 无权限设置群成员属性 401 确认当前用户有权限操作目标成员属性 否
    210 无权限设置群成员属性 403 确认当前用户有权限操作目标成员属性 否
    4 超过服务限制 400 减少操作频率或联系服务端提升配额 否
    305 服务已禁用 403 联系服务端开通群成员属性服务 否

getMembersAttributes

  • getMembersAttributes(
        input: GroupGetMembersAttributesInput,
    ): Promise<GroupMembersAttributesResult>

    批量获取当前群组中多个成员的自定义属性。

    Parameters

    Returns Promise<GroupMembersAttributesResult>

    返回按成员用户 ID 索引的属性集合。

    Example: 批量获取成员属性。

    const result = await client.groupManager.getGroup('group-1').getMembersAttributes({
      userIds: ['user-1', 'user-2'],
      keys: ['groupNamecard'],
    });

    可能出现的错误码

    Code 含义 HTTP 处理建议 可重试
    606 群组不存在 - 确认 groupId 正确且群组仍存在 否

Settings

Member Visibility

On This Page

Constructors
Properties
Methods
getSummarygetDetailrefreshupdateInfoupdateConfigschangeOwnerdestroyleavegetMembersremoveMembersgetAdminsaddAdminremoveAdmingetMuteListmuteMembersunmuteMembersmuteAllMembersunmuteAllMembersgetBlocklistblockMembersunblockMembersgetAllowlistaddUsersToAllowlistremoveUsersFromAllowlistcheckIfInAllowListcheckIfInMuteListgetAnnouncementupdateAnnouncementgetSharedFileListuploadSharedFiledeleteSharedFiledownloadSharedFilesetMemberAttributesgetMembersAttributes