Go SDK groups

This page covers groups in the Go SDK: creating and finding groups, editing group info, managing members, invitations and join requests, and join links. These are all REST methods on im.Client, with names and parameters matching the source.

The server defines what groups are (public or private, roles, how people join); this page only covers the values on the SDK side. For sending group messages, see Messages; for the full list of group events, see Events, sync and Store.

You want to	See
Create a group, list the user's groups and public groups	Create and find groups
Edit group info, dissolve or leave a group	Edit, dissolve and leave
Invite or remove members, set admins	Members
Handle group invitations and request to join	Invitations and join requests
Group online count and join links	Online count and join links
Check permissions	Permissions and errors

Basic fields

Common fields of im.GroupInfo:

Field	Description
`GroupID`	Group ID
`Name` / `AvatarURL` / `Description`	Group name, avatar and description
`Owner`	The owner's username
`MemberCount`	Current member count
`Public`	Whether it's public; `false` means private and invisible to non-members
`JoinMode`	How people join (a string defined by the server)
`MyRole`	The user's role in the group: `owner`, `admin` or `member`
`InfoVersion` / `MemberVersion`	Version numbers of the group info and the member list

Fields of im.GroupMember: Username, Nickname, AvatarURL, Role (the same three values) and JoinedAt.

Create and find groups

Method	Use	Key parameters
`c.CreateGroup(ctx, in)`	Create a group with the user as owner	Takes `im.CreateGroupInput`
`c.Group(ctx, groupID)`	Group details	Returns `*im.GroupInfo`
`c.LookupGroups(ctx, groupIDs)`	Look up groups in a batch	Up to 100 at a time
`c.MyGroups(ctx)`	All groups the user is in	Returns `[]im.GroupInfo`; the SDK gets a summary first, then looks them up in batches
`c.PublicGroups(ctx, cursor, limit)`	List public groups, paged	`cursor`: the previous page's `NextCursor`, `""` for the first page; `limit <= 0` uses the server default

Fields of im.CreateGroupInput: Name (required), Description, AvatarURL, Public (true for a public group; private by default) and Members (usernames of initial members, not including the user).

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

Creating a group returns its info

CreateGroup returns the new group's *im.GroupInfo. Initial members join or get an invitation depending on how the group handles them, and the SDK doesn't return a result per member. To confirm who actually joined, fetch the member list once with GroupMembers.

Edit, dissolve and leave

Method	Use	Key parameters
`c.UpdateGroup(ctx, groupID, name, description, avatarURL)`	Edit group info	All three are `*string`; `nil` leaves a field unchanged
`c.DismissGroup(ctx, groupID)`	Dissolve the group	Owner only
`c.LeaveGroup(ctx, groupID)`	Leave the group	—

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

After leaving, being removed or the group being dissolved, the group conversation's state (Membership in im.ConversationState) becomes left, removed or dismissed, announced by a conversation event (see Events, sync and Store).

Members

Method	Use	Key parameters
`c.GroupMembers(ctx, groupID)`	Member list	The SDK pages through automatically and returns all members
`c.AddGroupMembers(ctx, groupID, usernames)`	Invite members	Returns `[]im.GroupMemberResult`, one result per person
`c.RemoveGroupMember(ctx, groupID, username)`	Remove a member	Admins and owner only
`c.SetGroupMemberRole(ctx, groupID, username, role)`	Set a member's role	`role` is `admin` or `member`

AddGroupMembers follows the group's join settings, and one person failing doesn't affect the others. Even when the request returns no error, check each im.GroupMemberResult:

Field	Description
`Username`	The username for this item
`Status`	On success: `joined` (in the group), `invited` (waiting for the user to accept), `pending_review` (waiting for admin approval) or `already_member`
`Code`, `Message`	The error code and text when this item failed; a non-empty `Code` means inviting this user failed
`Details`	`json.RawMessage` error details; decode with `encoding/json` to read fields such as `reason`

Result and Error are deprecated fields kept for old data; new code should read the fields above.

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")

The invitation cooldown is set by the tenant under "App policies → Groups". group_invite_cooldown_enabled is off by default, so a user can be invited again right after leaving or declining. When it's on, the same group can't invite that user again within 24 hours: that result item's Code is rate_limited and reason in Details is declined_cooldown. With the cooldown off, invitations still need the user's acceptance or admin approval as configured. Adds by your server, the user's own join requests and join links aren't affected by the invitation cooldown. The 24-hour cooldown after a join request is declined always applies. For the settings, see Group runtime policies.

Invitations and join requests

Method	Use	Key parameters
`c.GroupInvitations(ctx)`	Group invitations received	Returns `[]im.GroupInvitation` (`InvitationID`, `GroupID`, `GroupName`, `Inviter`)
`c.AcceptGroupInvitation(ctx, invitationID)`	Accept an invitation	Returns the joined group's `*im.GroupInfo`
`c.DeclineGroupInvitation(ctx, invitationID)`	Decline an invitation	—
`c.MyGroupApplications(ctx)`	Join requests the user sent	Returns `*im.Page[map[string]any]`; read the fields the server defines
`c.ApplyJoinGroup(ctx, groupID, reason)`	Request to join a group	`reason` can be empty
`c.WithdrawGroupApplication(ctx, groupID)`	Withdraw the request for this group	—

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
}

Changes to join requests and invitations arrive as events: im.EventGroupRequestCreated for new ones and im.EventGroupRequestHandled once handled. Changes to the group itself are im.EventGroupCreated, im.EventGroupInfoChanged, im.EventGroupMembersAdded, im.EventGroupMembersRemoved, im.EventGroupMembersUpdated and im.EventGroupDismissed, all of whose payloads parse into im.GroupEventData (GroupID, Username, Role, Reason and so on).

Online count and join links

Method	Use	Key parameters
`c.GroupOnlineCount(ctx, groupID)`	Number of group members online	Returns `int64`; the app must turn on presence
`c.JoinLink(ctx, groupID)`	Get a join link	Returns the link string
`c.JoinByLink(ctx, link)`	Join through a link	Returns the joined group's `*im.GroupInfo`

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

Permissions and errors

The server checks permissions

The Go SDK doesn't check permissions locally. Insufficient roles (such as a regular member calling UpdateGroup or an admin calling DismissGroup), not being a member, or a missing group all go to the server and are refused, returning *im.APIError. Check codes such as permission_denied, not_found and invalid_argument with im.IsCode (for all codes, see Events, sync and Store). For UI decisions such as "can edit group info", read GroupInfo.MyRole first.

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

Send group messages

Group messages use the same send methods as one-to-one chats, with im.ToGroup(groupID) as the target:

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

For message types, mentions, replies and read receipts, see Messages.

Go SDK groups ​

Basic fields ​

Create and find groups ​

Edit, dissolve and leave ​

Members ​

Invitations and join requests ​

Online count and join links ​

Permissions and errors ​

Send group messages ​

See also ​