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 的 Result 常见取值：ok、already_member（原本就是成员）、not_member（移出时原本不是成员）；失败的项带 Error（*im.APIError），一个人失败不影响其他人。

results, err := c.AddGroupMembers(ctx, g.GroupID, []string{"bob", "lisi"})
if err != nil {
    log.Fatal(err) // 整个请求失败
}
for _, r := range results {
    if r.Result != "ok" {
        fmt.Println(r.Username, r.Result, r.Error)
    }
}

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

邀请与入群申请

方法	用途	关键参数
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), "大家好")

消息类型、@、回复、已读回执等见消息。

另见

• 用户、好友与在线状态：本人资料、好友与申请、黑名单。
• 消息：发送与操作消息（im.ToGroup）。
• 事件、同步与 Store：群相关事件、登录后同步与错误处理。