Skip to main content

Build group chat with MLS and XMTP

Secure group chat is an important part of every messaging app. In this guide, we cover the essentials of building group chat using XMTP, from the initial steps of ensuring that potential members have v3 identities and starting a new group chat to managing membership and synchronizing group chat details.

XMTP group chat is based on the MLS specification and can include anywhere from 1 to 400 members.

To learn about group chat security and encryption, see Group Chat concepts.

Overview​

Here are some key points to understand before building group chat with XMTP.

Group chat keys work per app installation​

An app installation is registered to a user. Group chat messages a user sends using an app installation are encrypted so only that app installation can decrypt them. This is because keys are generated to work per app installation. App installations do not share the same keys.

To learn more, see Installations.

⚠️ Important: Manage actions that make a local database inaccessible​

Because group chat keys work per app installation, there are user actions that make an app installation’s local database inaccessible to other app installations.

Here are the actions:

  • A user logs out of an installation of your app and logs into a different app installation on their device.
  • A user deletes an installation of your app from their device.

As a result of either of these actions, the user will lose access to the local database for the app installation, which includes all group chat messages they sent using the installation of your app on their device.

As an app developer, this concept is important to understand and communicate to your users. For example, you might consider using this language:

If you log out of <app name> and log into a different app on this device, or delete <app name> from this device, you will lose access to all group chat messages you sent using this installation of <app name> on this device.

To enable your users to avoid losing access to their local databases, allow them to store their local cache in iCloud or Google Cloud, for example. This option will enable message persistence within a single app ecosystem.

For example, let's say that App A enables users to store their local cache in iCloud. A user does this and then deletes App A from their device. The user can reinstall App A and restore their local cache from iCloud.

However, this option does not allow users to restore a local cache across apps. For example, a local cache from App A can't be used to restore message history to App B. In this case, the best solution will be the forthcoming XMTP Message History server.

Web support for group chat​

The XMTP JavaScript SDK and React SDK don’t yet provide web support for group chat. However, if you want to integrate group chat backend support, you can use the experimental Node SDK.

Web support for group chat is lagging due to technical challenges related to integrating WebAssembly (WASM) and its extensions. WASM sandbox cannot access the operating system directly, which is necessary for tasks like file reads. WASI extends WASM to allow operating system interaction, but it comes with its own set of challenges. For example, current WASI 0.2 has no built-in way to handle asynchronous operations effectively. The team is working toward solutions.

Push notifications​

Group chat supports push notifications. To learn more, see the Notifications with XMTP section.

XMTP V3 SDK example apps​

If you’d like to dive right into exploring the code, check out the example apps in these XMTP V3 SDKs that support group chat:

Understand group chat permissions​

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

To learn more, see Group Permissions.

Admin types​

There are two kinds of administrators: super admins and admins. The group creator starts as a super admin, who has the most permissions so that a normal admin cannot remove the creator or destroy a group.

Permissions​

These are the current permissions allowed for a group:

  • Add member
  • Remove member
  • Update metadata
  • Add admin
  • Remove admin
  • Update permissions

Permission options​

These are the permission options available for each permission:

  • Unspecified
  • Allow
  • Deny
  • Allow if admin or super admin
  • Allow if super admin

You can list, add, and remove members from a group chat. Only the group chat creator (super admin) has permission to add or remove members. This restriction ensures that only authorized individuals can modify the participant list.

Create a client that supports group chat​

By default, XMTP V3 clients support XMTP V2 messages, which include direct messages only.

If you want your app to support group chat offered by V3, you must explicitly configure your client to support group chat.

appContext is used for Android only. It is required if enableV3 is true.

dbEncryptionKey is optional. For Android, if not provided, a key is created and stored for you. For iOS, if not provided, the database remains unencrypted.

XMTP.Client.create(signer, {
  env: "production,
  enableV3: true', DEFAULT false
  dbDirectory: "mydbdir", OPTIONAL pass in any dir otherwise, default is `xmtp_db`
  dbEncryptionKey: 32bytearray,
})

Create group chats​

Check if user has V3 identity​

Only users with V3 identities can participate in a group chat. For this reason, the first step to creating a group chat is to check if a potential group member has a V3 identity.

To learn more about V3 identities, see Multi-wallet Identity in V3.

const canMessageV3 = await client.canGroupMessage([alix.address, bo.address]);

Create a group chat​

To create a group chat, each of the specified member addresses must have a V3 identity and have used the identity to start up an app installation that supports group chat.

const group = await client.conversations.newGroup(
  [anotherClient.address],
  // set the permission level for the group. Options include "admin_only", where only the creator is an admin, or "all_members" to make everyone an admin.
  {
    permissionLevel: "admin_only",
    name: "Group Name",
    imageUrlSquare: "<URL>",
  },
);
tip

If a member is using an app installation that doesn’t support group chat, consider sending them a message from your app to let them know how to join the group chat. For example:

<sender address> added you to a group chat, but you aren't using an app that supports group chat. To join the group chat, use an app that supports group chat, such as <your app name>.

Display group chats​

Display group chats associated with the current client.

Get group chats​

tip

In this documentation, “group chat” refers to "group chat conversations." As with XMTP direct message conversations, conversations do not include the messages in the conversation.

//First fetch new data from the network
await client.conversations.syncGroups();
//Get the updated group list
const groups = await client.conversations.listGroups();

Get group chats and direct message conversations:

// List all conversations, including both group and individual
val conversations = client.conversations.listAll()

Get group chat messages​

await group.messages();

Check if user is active in a group chat​

Use the isActive property to check if the current user is still a participant in a group chat. For example, if a user is removed from a group chat, the group chat will not be active for the user.

Use this status to adjust the user’s interface accordingly, such as removing the user’s ability to send messages in the group chat.

const isActive = await group.isActive();

Send a message in a group chat​

Group chat supports all message types you can send using direct message conversations, including Subscription Frames, replies, reactions, attachments, and read receipts.

const group = await client.conversations.newGroup([
  walletAddress1,
  walletAddress2,
]);
// Send a message
await group.send("Hello, group!");

Stream group chats​

Stream group chat updates​

// Listen for group chat updates
const streamGroups = async (client) => {
  const groups = [];
  const cancelStreamGroups = await client.conversations.streamGroups(
    (group) => {
      groups.push(group);
    },
  );

  // Use cancelStreamGroups() to stop listening to group updates
};

Stream group chats and direct message conversations:

const streamAllConversations = async (client) => {
  const allConvos = [];
  const cancelStreamAll = await client.conversations.streamAll(
    (conversation) => {
      allConvos.push(conversation);
    },
  );

  // Use cancelStreamAll() to stop listening to all conversation updates
};

Stream group chat messages and membership updates​

Stream messages and member management updates in group chats, such as adding and removing members:

// Assuming `group` is an existing group chat object
const streamGroupMessages = async (group) => {
  const cancelGroupMessageStream = await group.streamGroupMessages(
    async (message) => {
      console.log(`New message: ${message.content}`);
      // Membership updates
      if (message.contentTypeId === ContentTypes.GroupMembershipChange) {
        const addresses = await group.memberAddresses();
        // Get new members
        console.log(addresses); // Example usage of addresses
      }
    },
  );

  // Use cancelGroupMessageStream() to stop listening to group updates
  return cancelGroupMessageStream;
};

Stream messages in group chats and direct message conversations:

const streamAllGroupMessages = async (client) => {
  const allConvos = [];
  const cancelStreamAllGroupMessages =
    await client.conversations.streamAllMessages(async (message) => {
      console.log(`New message: ${message.content}`);
    });
  // Use cancelStreamAllGroupMessages() to stop listening to all conversation updates
};

Sync group chats​

Calling sync() for a group or groups gets any updates since the last sync and adds them to the local database. Be sure to periodically synchronize each group chat to ensure your app has the latest group chat details, including the most recent messages, member list, and group chat details, for example.

Updates are also retrieved and added to the local database when streaming and when the user takes an action.

When your user sends a message, you don’t need to sync with the network for them to see their own message. The message gets written to their local database, and it shows up immediately for them. The same applies when your user creates a group.

See ⚠️ Important: Manage actions that make a local database inaccessible.

This means that everything XMTP gets from the network for the user is stored in this local database and never needs to be fetched again. Extra syncing isn’t costly as the process won’t fetch data it already has, but this is just an explanation of why syncing isn’t necessary for data created by a user’s own actions.

To learn more, see Local Database and Syncing.

However, you must sync (or use streaming) to enable other users to see the group chats and messages your user created and sent.

Sync group chat updates​

// List groups without syncing with the network
let groups = await client.conversations.listGroups();
// groups length might be 0 if not synced after group creation
// Sync groups and list again
await client.conversations.syncGroups();
groups = await client.conversations.listGroups();
console.log(groups.length); // groups length reflects the actual number of groups

Synchronize group chats and direct message conversations:

let conversations = await client.conversations.listAll();

Sync group chat messages and membership updates​

Use sync() to synchronize group chat data, such as new messages or membership changes.

// Assume group is an existing group chat object
await group.sync(); // Synchronizes the group's messages and members
// Fetch messages without network sync
const messages = await group.messages(true);
console.log(messages.length); // Shows messages fetched from local data

Manage group chat admins​

Here's an overview of how group chat admin statuses work:

  • Everyone in a group chat is a member.
  • A member can be granted admin or super admin status.
    If the member's admin or super admin status is removed, they are still a member of the group chat.
  • By default, only a member with super admin can add and remove admin and super admin statuses.
    Also by default, the group creator is the only member with super admin status.
info

By design, checking admin permission status by wallet address is not supported. Instead, look up the inboxID for that wallet address, then use the calls below.

Check if inbox ID is an admin​

// Assume group is an existing group chat object for client
const isAdmin = await.group.isAdmin(adminClient.inboxID)

Check if inbox ID is a super admin​

//Assume group is an existing group chat object for client
const isSuperAdmin = await group.isSuperAdmin(client.inboxID);

List admins​

await group.listAdmins();

List super admins​

await group.listSuperAdmins();

Add admin status to inbox ID​

await group.addAdmin(client.inboxID);

Add super admin status to inbox ID​

await group.addSuperAdmin(client.inboxID);

Remove admin status from inbox ID​

await group.removeAdmin(client.inboxID);

Remove super admin status from inbox ID​

await group.removeSuperAdmin(client.inboxId);

Manage group chat membership​

Add members by inbox ID​

await group.addMemberInboxIds([inboxId]);

Add members by address​

await group.addMembers([walletAddress]);

Remove members by inbox ID​

await group.removeMemberInboxIds([inboxId]);

Remove members by address​

await group.removeMembers([walletAddress]);

Get inbox IDs for members​

await group.memberInboxIds();

Get addresses for members​

const members = await group.members();
const addresses = members.map((member) => member.addresses);

Get the inbox ID that added the current member​

// this API is experimental and may change in the future

const addedByInboxId = await group.addedByInboxId();

With XMTP, in addition to permissions that enable members to add and remove members, user consent preferences also apply.

User consent preferences enable you to give a user the option to allow or deny contact from a group ID, inbox ID, or address.

For example, your app can check inboxId values using the isInboxIdAllowed() or isInboxIdDenied() functions. Then, based on your app's design and the user's settings, your app can determine how and whether a group chat and message should be displayed for a user.

To learn more, see Spam Protection.

To learn how to allow and deny contact by address, see Universal allow/block preferences.

To learn how to keep user consent preferences synchronized, see Synchronize user consent preferences.

Allow or deny contact by wallet in group chat​

// Allow
await contact.allow([walletAddress]);

// Deny
await contact.deny([walletAddress]);

Allow or deny contact by inbox ID in group chat​

// Allow
await contact.allowGroup([groupId]);

// Deny
await contact.denyGroup([groupId]);

Allow or deny contact by group chat ID​

// Allow group
await contact.allowGroup([groupId]);

// Deny a group
await contact.denyGroup([groupId]);

Allow or deny contact from inbox ID​

Enable a user to explicitly allow or deny contact from an inbox ID.

// Allow
await client.contacts.allowInboxes([client.inboxId]);

// Deny
await client.contacts.denyInboxes([client.inboxId]);

Check if contact from a group chat ID is allowed or denied for a user.

// Check if contact by a group is allowed for a member
const isAllowed = await group.isGroupAllowed(groupId);

// Check if contact by a group is denied for a member
const isDenied = await group.isGroupDenied(groupId);

Check if contact from an inbox ID is allowed or denied for a user.

await client.contacts.isInboxAllowed(client.inboxId);

Manage group chat metadata​

Group chats can have metadata, like names and images. Metadata can help users more easily identify their group chats. You can also set group chat metadata when creating a group chat.

Get a group chat name​

const groupName = await group.groupName();

Update a group chat name​

await group.updateName("New Group Name");

Get a group chat image URL​

const groupName = await group.imageUrlSquare();

Update a group chat image URL​

await group.updateImageUrlSquare("ImageURL");

Was the information on this page helpful?
powered by XMTP

On this page