Manage group permissions

Robust group chat permissions are key to providing users with a friendly and safe group chat experience.

Understand the group permissions system

Member statuses

Member statuses are the roles that can be assigned to each participant (inbox ID) in a group chat. These are the available member statuses:

• Member
  • Everyone in a group chat is a member. A member can be granted admin or super admin status. If a member's admin or super admin status is removed, they are still a member of the group.
• Admin
• Super admin

Options

Use options to assign a role to a permission. These are the available options:

• All members
• Admin only
  • Includes super admins
• Super admin only

Permissions

Permissions are the actions a group chat participant can be allowed to take. These are the available permissions:

• Grant admin status to a member
• Remove admin status from a member
• Add a member to the group
• Remove a member from the group
• Update group metadata, such as group name, description, and image
• Update group permissions on an item-by-item basis, such as calling updateNamePermission or updateAddMemberPermission . To learn more, see Group.kt in the xmtp-android SDK repo.

The following permissions can be assigned by super admins only. This helps ensure that a “regular” admin cannot remove the super admin or otherwise destroy a group.

• Grant super admin status to a member
• Remove super admin status from a member
• Update group permissions

How the group permissions system works

When a group is created, all groups have the same initial member "roles" set:

• There is one super admin, and it is the group creator
• There are no admins
• Each user added to the group starts out as a member

The super admin has all of the available permissions and can use them to adjust the group's permissions and options.

As the app developer, you can provide a UI that enables group participants to make further adjustments. For example, you can give the super admin the following permission options for group members when creating the group:

• Add members
• Update group metadata

You can use member statuses, options, and permissions to create a custom policy set. The following table represents the valid policy options for each of the permissions:

If you aren't opinionated and don't set any permissions and options, groups will default to using the delivered All_Members policy set, which applies the following permissions and options:

• Add member - All members
• Remove member - Admin only
• Add admin - Super admin only
• Remove admin - Super admin only
• Update group permissions - Super admin only
• Update group metadata - All members

To learn more about the All_Members and Admin_Only policy sets, see group_permissions.rs in the LibXMTP repo.

Manage group chat admins

Check if inbox ID is an admin

const isAdmin = group.isAdmin(inboxId);

Check if inbox ID is a super admin

const isSuperAdmin = group.isSuperAdmin(inboxId);

List admins

const admins = group.admins;

List super admins

const superAdmins = group.superAdmins;

Add admin status to inbox ID

await group.addAdmin(inboxId);

Add super admin status to inbox ID

await group.addSuperAdmin(inboxId);

Remove admin status from inbox ID

await group.removeAdmin(inboxId);

Remove super admin status from inbox ID

await group.removeSuperAdmin(inboxId);

Manage group chat membership

Add members by inbox ID

The maximum group chat size is 250 members.

await group.addMembers([inboxId]);

Remove member by inbox ID

await group.removeMembers([inboxId]);

Leave a group

A member can remove themselves from a group by calling leaveGroup(). After leaving, the group becomes inactive for that member.

A member who is the super admin of the group cannot leave the group. By default, the group creator is a super admin.

await group.leaveGroup();
 
// Sync to update group state
await group.sync();
 
// Verify the group is now inactive
const isActive = await group.isActive(); // Returns false

Check if member is pending removal

After a user calls leaveGroup(), you can check if their removal is still being processed using the membershipState() method. This is useful for showing appropriate UI while the group removal is being finalized.

// After calling leaveGroup()
group.leaveGroup()
 
// Check if removal is still pending
val state = group.membershipState()
 
if (state == FfiGroupMembershipState.PENDING_REMOVE) {
    // User has requested to leave, but removal not yet fully processed
    println("Processing your departure from the group")
}

The PENDING_REMOVE state indicates that the user has called leaveGroup() but the removal has not yet been fully processed by the client. After syncing and processing completes, the group will become inactive.

Get inbox IDs for members

const inboxId = await client.findInboxIdByIdentities([
  bo.identity,
  caro.identity,
]);

Get identities for members

// sync group first
await group.sync();
 
// get group members
const members = await group.members();
 
// map inbox ID to account identity
const inboxIdIdentityMap = new Map(
  members.map((member) => [member.inboxId, member.accountIdentity])
);

Get the inbox ID that added the current member

const addedByInboxId = group.addedByInboxId;