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 step of ensuring that potential members have v3 identities to starting a new group chat to 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, encryption, and other details, see Group chat concepts and protocols.

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 XMTP 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 Build push notifications.

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:

• XMTP React Native SDK Example
• XMTP Android SDK Example
• XMTP iOS SDK Example

Create group chats

Take these steps to create group chats.

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

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

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>",
  },
);

Display group chats

Use these methods to display group chats associated with the current client.

Get group chats

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

// 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 messages in group chats

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

Use these methods to 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
};

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
};

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;
};

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.

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

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