群組

群組（下文簡稱群）有固定的成員，適合同事群、家長群、興趣群等場景。使用者可以在客戶端建群、邀請他人、申請加入公開群、透過入群連結加入；群主和管理員可以修改群資料、管理成員、審批入群申請。

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，常見的有：

`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`	使用者不存在

邀請冷卻（group_invite_cooldown_enabled）在控制檯的群組執行策略中設定：

預設關閉：對方退群或拒絕邀請後，可以立即再次邀請。
開啟後：對方退群或拒絕邀請後 24 小時內，這個群不能再邀請他。
冷卻只限制邀請。服務端直接新增、本人申請、入群連結不受影響；本人確認、管理員審批這些條件照常適用。
與此無關：入群申請被拒絕後，申請人 24 小時內不能再申請，這條始終生效。

HTTP 請求成功不代表所有人已入群，應逐項檢查 results，分別提示已入群、等待本人確認、等待管理員審批或失敗原因。

整個請求失敗的情況：普通成員在 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()

拒絕入群邀請。之後預設可立即再次收到邀請；僅在應用開啟 group_invite_cooldown_enabled 時，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