Go SDK 群組

本頁介紹 Go SDK 的群組功能：建群、查群、修改群資料、成員管理、邀請與入群申請、入群連結。都是 im.Client 上的方法，REST 實現，方法名與引數與原始碼一致。

群的概念（公開/私有、角色、加群方式）由服務端定義，這裡只寫 SDK 側的欄位取值。傳送群訊息見訊息，群相關事件的完整列表見事件、同步與 Store。

要做什麼	看哪裡
建群、列出我的群和公開群	建群與查群
改群資料、解散、退群	修改群資料與解散、退群
邀請、移出成員，設定管理員	成員
處理群邀請、申請入群	邀請與入群申請
群線上人數、入群連結	群線上人數與入群連結
判斷有沒有許可權	許可權與錯誤

基本欄位

im.GroupInfo 的常用欄位：

欄位	說明
GroupID	群 ID
Name / AvatarURL / Description	群名稱、頭像、簡介
Owner	群主的使用者名稱
MemberCount	當前人數
Public	是否公開群；false 為私有群，非成員不可見
JoinMode	加群方式（服務端定義的字串）
MyRole	本人在群裡的角色：owner（群主）、admin（管理員）、member（普通成員）
InfoVersion / MemberVersion	群資料、成員列表的版本號

im.GroupMember 的欄位：Username、Nickname、AvatarURL、Role（同上三種）、JoinedAt。

建群與查群

方法	用途	關鍵引數
c.CreateGroup(ctx, in)	建群，本人為群主	入參 im.CreateGroupInput
c.Group(ctx, groupID)	群詳情	返回 *im.GroupInfo
c.LookupGroups(ctx, groupIDs)	批次查群	一次最多 100 個
c.MyGroups(ctx)	我加入的全部群	返回 []im.GroupInfo，SDK 內部先取摘要再批次查詢
c.PublicGroups(ctx, cursor, limit)	公開群列表，可翻頁	cursor 取上一頁的 NextCursor，首頁傳 ""；limit <= 0 時用服務端預設值

im.CreateGroupInput 的欄位：Name（必填）、Description、AvatarURL、Public（true 建公開群，預設私有群）、Members（初始成員的使用者名稱，不含自己）。

ctx := context.Background()

g, err := c.CreateGroup(ctx, im.CreateGroupInput{
    Name:        "产品研发群",
    Description: "产品和研发日常沟通",
    Public:      false,
    Members:     []string{"bob"}, // 初始成员不含自己
})
if err != nil {
    log.Fatal(err)
}
fmt.Println(g.GroupID, g.MyRole) // owner

建群返回群資訊

CreateGroup 返回新群的 *im.GroupInfo。初始成員按各群的處理方式入群或收到邀請，SDK 不逐個返回他們的處理結果；需要確認實際入群名單時，用 GroupMembers 拉一次成員列表。

修改群資料與解散、退群

方法	用途	關鍵引數
c.UpdateGroup(ctx, groupID, name, description, avatarURL)	修改群資料	三個引數都是 *string，傳 nil 表示不修改
c.DismissGroup(ctx, groupID)	解散群	僅群主
c.LeaveGroup(ctx, groupID)	退群	—

name := "产品研发群（2 期）"
desc := ""
_, err := c.UpdateGroup(ctx, g.GroupID, &name, &desc, nil) // 只改名称，简介清空，头像不动

退群、被移出或群解散後，對應群會話的狀態（im.ConversationState 的 Membership）會變為 left、removed 或 dismissed，並透過會話事件通知（見事件、同步與 Store）。

成員

方法	用途	關鍵引數
c.GroupMembers(ctx, groupID)	成員列表	SDK 自動翻頁，一次取回全部成員
c.AddGroupMembers(ctx, groupID, usernames)	邀請成員	返回 []im.GroupMemberResult，逐人給出結果
c.RemoveGroupMember(ctx, groupID, username)	移出成員	僅管理員/群主
c.SetGroupMemberRole(ctx, groupID, username, role)	設定成員角色	role 為 admin 或 member

AddGroupMembers 按群的加群設定處理，某個人失敗不影響其他人。請求沒有返回錯誤時，仍須逐項檢查 im.GroupMemberResult：

欄位	說明
Username	本項對應的使用者名稱
Status	成功結果：joined 已入群、invited 等待本人確認、pending_review 等待管理員審批、already_member 原本就是成員
Code、Message	單項失敗時的錯誤碼和提示文字；Code 非空表示該使用者邀請失敗
Details	json.RawMessage，錯誤詳情，可用 encoding/json 解碼並讀取 reason 等欄位

Result 和 Error 為相容舊資料保留的棄用欄位，新程式碼應讀取上表欄位。

results, err := c.AddGroupMembers(ctx, g.GroupID, []string{"bob", "lisi"})
if err != nil {
    log.Fatal(err) // 整个请求失败
}
for _, r := range results {
    if r.Code != "" {
        fmt.Println(r.Username, r.Code, r.Message, string(r.Details))
        continue
    }
    fmt.Println(r.Username, r.Status) // 区分已入群、已发出邀请和等待审批
}

err = c.SetGroupMemberRole(ctx, g.GroupID, "bob", "admin")

邀請冷卻由租戶在“應用策略 → 群組”中設定，group_invite_cooldown_enabled 預設關閉，退群或拒絕邀請後可立即再次邀請；開啟後，同一群在 24 小時內不能再次邀請該使用者，對應結果項的 Code 為 rate_limited、Details 中的 reason 為 declined_cooldown。關閉冷卻後仍須滿足本人確認、管理員審批等條件；服務端直接新增、本人申請和入群連結不受邀請冷卻影響。入群申請被拒絕後的 24 小時冷卻始終生效。配置見群組執行策略。

邀請與入群申請

方法	用途	關鍵引數
c.GroupInvitations(ctx)	收到的群邀請	返回 []im.GroupInvitation（InvitationID、GroupID、GroupName、Inviter）
c.AcceptGroupInvitation(ctx, invitationID)	接受邀請	返回入群后的 *im.GroupInfo
c.DeclineGroupInvitation(ctx, invitationID)	拒絕邀請	—
c.MyGroupApplications(ctx)	我發出的入群申請	返回 *im.Page[map[string]any]，欄位按服務端定義自行取值
c.ApplyJoinGroup(ctx, groupID, reason)	申請加入群	reason 可為空串
c.WithdrawGroupApplication(ctx, groupID)	撤回對這個群的申請	—

invs, err := c.GroupInvitations(ctx)
if err != nil {
    log.Print(err)
}
for _, inv := range invs {
    fmt.Println(inv.Inviter, "邀请你加入", inv.GroupName)
}
// 处理第一条
if len(invs) > 0 {
    g, err := c.AcceptGroupInvitation(ctx, invs[0].InvitationID)
    _ = g
    _ = err
}

入群申請與邀請的狀態變化以事件送達：新的請求 im.EventGroupRequestCreated，被處理後 im.EventGroupRequestHandled。群本身的變化有 im.EventGroupCreated、im.EventGroupInfoChanged、im.EventGroupMembersAdded、im.EventGroupMembersRemoved、im.EventGroupMembersUpdated、im.EventGroupDismissed，載荷都可解析為 im.GroupEventData（GroupID、Username、Role、Reason 等）。

群線上人數與入群連結

方法	用途	關鍵引數
c.GroupOnlineCount(ctx, groupID)	群線上人數	返回 int64；需要應用開啟線上狀態
c.JoinLink(ctx, groupID)	獲取入群連結	返回連結字串
c.JoinByLink(ctx, link)	透過連結入群	返回入群后的 *im.GroupInfo

count, err := c.GroupOnlineCount(ctx, g.GroupID)
if im.IsCode(err, im.CodePermission) {
    fmt.Println("应用未开启在线状态，或可见范围不允许")
}

許可權與錯誤

許可權由服務端校驗

Go SDK 不在本地預檢許可權：角色不夠（如普通成員調 UpdateGroup、管理員調 DismissGroup）、不是群成員、群不存在等，請求都會發到服務端並被拒絕，方法返回 *im.APIError。用 im.IsCode 按 permission_denied、not_found、invalid_argument 等碼判斷（全部碼見事件、同步與 Store），介面上“能否修改群資料”之類的判斷先讀 GroupInfo.MyRole。

_, err := c.UpdateGroup(ctx, g.GroupID, &name, nil, nil)
if im.IsCode(err, im.CodePermission) {
    // 本人不是管理员/群主，隐藏编辑入口
}

傳送群訊息

群訊息與單聊共用一套傳送介面，用 im.ToGroup(groupID) 指定目標：

m, err := c.SendText(ctx, im.ToGroup(g.GroupID), "大家好", nil)

訊息型別、@、回覆、已讀回執等見訊息。

另見

• 使用者、好友與線上狀態：本人資料、好友與申請、黑名單。
• 訊息：傳送與操作訊息（im.ToGroup）。
• 事件、同步與 Store：群相關事件、登入後同步與錯誤處理。