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:

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

Check if a user has a 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>.

Get group chats​

Get group chats associated with the current client.

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

Check if a 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!");

Get group chat messages​

await group.messages();

Synchronize group chat details​

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.

Synchronize group chats​

// 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();

Synchronize group chat data​

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

Stream group chats​

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

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

Manage group chat membership​

Add members by address​

await group.addMembers([walletAddress]);

Remove members by address​

await group.removeMembers([walletAddress]);

Get addresses for members​

members returns a members Type, which has a list of addresses, an inboxId, and a permissionsType.

const members =await group.members();

Get the inbox ID that added the current member​

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

const addedByInboxId =await group.addedByInboxId();

Manage group chat metadata​

Group chats can have metadata, like names and images. Metadata can help users more easily identify their group chats.

Get a group chat name​

const groupName =await group.groupName();

Update a group chat name​

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

Was the information on this page helpful?
powered by XMTP

On this page