Manage group chats with XMTP

Secure group chats are an important part of every messaging app. In this guide, we delve into the essentials of using XMTP for creating secure group chats. From the initial steps of starting a new group chat, listing and caching conversations for quick access, to advanced topics like managing group members and synchronizing message history data across devices.

Group Chats are Per Installation

Group chats in XMTP are specific to each installation. This means that while you will see your group chat conversations across different devices, you will not see the historical messages within those chats automatically. Each group chat's message history is tied to the device where it was started. Consequently, there is no message history synced across devices. When you sign in on a new device, you will be able to see existing group chat conversations but will only receive new messages going forward. This behavior is specific to group conversations.

Create a group chat

Initiate a new group chat with a list of specified addresses. To create a group, the recipient must have already started their client at least once on the XMTP network.

const group = await client.conversations.newGroup(
  [walletAddress1, walletAddress2],
  // Set permissions for the group. Options include "creator_is_admin" where only the creator has admin rights, or "everyone_is_admin" where all members are admins.
  { permissions: "creator_is_admin" },
);

val group = client.conversations.newGroup(listOf(walletAddress1,walletAddress2))

let group = try await client.conversations.newGroup(with: [walletAddress1, walletAddress2])

The maximum amount of addresses allowed is 250.

List group chat conversations

Retrieve all existing group chat conversations associated with the current XMTP client. Refer to the Conversations section for more details.

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

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

List all you conversation for both group and individual conversations

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

//First fetch new data from the network
try await client.conversations.sync()
//Get the updated group list
let groups = try await client.conversations.groups()

List all you conversation for both group and individual conversations

let groups = try await client.conversations.list(includeGroups: true)

Send a message in a group chat

Send a message to an existing group chat. Refer to the Messages section for more details.

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

val group = client.conversations.newGroup(listOf(walletAddress1,walletAddress2))
//Send a message
group.send("Hello, group!")

let group = try await client.conversations.newGroup(with: [walletAddress1, walletAddress2])
//Send a message
try await group.send(content: "Hello, group!")

Check if a group chat is active

The isActive property indicates whether the current user is still a participant in the group chat. If the group chat is not active for the user, it typically means the user has been removed from the group. Developers should use this status to adjust the user interface accordingly. If a group chat is not active for a user, the application should hide or disable functionalities such as sending messages, adding, or removing members. This ensures a good user experience and prevents actions that are not permissible due to the user's status in the group chat.

const isActive = await group.isActive();

val isActive = group.isActive()

var isActive = try group.isActive()

Synchronizing group conversations

XMTP's syncGroups brings the current data from the network and updates local DB, reflecting new groups or membership changes. Use syncGroups to:

After Signing In: Immediately update group conversation data.
Periodically: Keep data current based on your app's requirements.
After Receiving a Notification: Reflect changes in group membership prompted by notifications.

await client.conversations.syncGroups();

client.conversations.syncGroups()

List all you conversation for both group and individual conversations.

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

try await client.conversations.sync()

Synchronizing group details and messages

To ensure your application has the latest group chat details, including member list and the most recent messages, it's crucial to periodically synchronize each group chat. This can be particularly important after joining a group, adding new members, or sending messages. Use the sync() method on a group chat object to update its state with the latest information from the XMTP network.

// Assuming `group` is an existing group chat object
await group.sync();

// Assuming `group` is an existing group chat object
group.sync()

try await client.conversations.sync()

Manage group chat members

You can list, add and remove members from a group chat. The current limit is 250. Only the creator of the group chat has the permissions to add or remove members. This restriction ensures that only authorized individuals can modify the participant list. Developers should design their application's user interface and functionality with this consideration in mind, ensuring that options to add or remove members are only available to the group's creator.

List group members

Retrieve a list of wallet addresses for all members in the group chat

await group.sync();
const members = await group.memberAddresses();

group.sync()
val members = group.memberAddresses()

try await group.sync()
let members = group.memberAddresses()

Add group members

Add new members to an existing group chat using its wallet address.

await group.addMembers([walletAddress]);

group.addMembers(listOf(walletAddress))

try await group.addMembers(addresses: [walletAddress])

Remove group members

Remove a member from an existing group chat using its wallet address

await group.removeMembers([walletAddress]);

group.removeMembers(listOf(walletAddress))

try await group.removeMembers(addresses: [walletAddress])

Listen for new messages in a group chat

Streams allow real-time monitoring of new messages in a group chat. Here's how you can set up a stream for message updates. Refer to the Streams section for more details.

// Assuming `group` is an existing group chat object
const streamGroupMessages = async (group) => {
  const cancelGroupMessageStream = await aliceGroup.streamGroupMessages(
    (message) => {
      console.log(`New message: ${message.content}`);
    },
  );

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

// Stream new messages in a group chat
val group = client.conversations.newGroup(listOf(walletAddress1, walletAddress2))
val messageStream = group.streamMessages()

// Collect from the Flow to receive messages
messageStream.collect { message ->
    print("New message from ${message.senderAddress}: ${message.body}")
}

// Assuming `group` is an existing group chat object
for try await message in group.streamMessages() {
    print("New message: \(message.content)")
}

Listen for group chat updates

Monitor updates in group chats, including member management activities like adding and removing members as well as the creation of new 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
};

And for streaming all conversations, including individual and groups:

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 updates for all group conversations
val groupsStream = client.conversations.streamGroups()

groupsStream.collect { group ->
    println("New or updated group: ${group.id}")
}

Keep your conversation list current by streaming updates for both group and individual conversations.

// Stream updates for all conversations, including individual and groups
val conversationsAndGroupsStream = client.conversations.streamAll()

allConversationsStream.collect { grouporconv ->
    println("New or updated group or conversation: ${grouporconv.id}")
}

// Stream updates for all group conversations
for try await group in client.conversations.streamGroups() {
    print("New or updated group: \(group.id)")
}

And for streaming all conversations, including individual and groups:

// Stream updates for all conversations, including individual and groups
for try await conversation in client.conversations.streamAll() {
    print("New or updated conversation: \(conversation.id)")
}

Note on conversations and messages in group chats

It's important to note that all the features and methods described in the Conversations and Messages documentation are fully applicable to group chats as well. This includes starting new conversations, checking if an address is on the network, sending messages, and listing existing conversations. XMTP's API design ensures that you can manage group chats with the same ease and flexibility as one-on-one conversations.

This means that whether you're working with individual conversations or group chats, the process for managing them remains consistent, allowing for a unified and streamlined development experience across different types of communication within XMTP.

Manage group chats with XMTP

Create a group chat​

List group chat conversations​

Send a message in a group chat​

Check if a group chat is active​

Synchronizing group conversations​

Synchronizing group details and messages​

Manage group chat members​

List group members​

Add group members​

Remove group members​

Listen for new messages in a group chat​

Listen for group chat updates​

Note on conversations and messages in group chats​