Create conversations

Check if an identity is reachable

The first step to creating a conversation is to verify that participants’ identities are reachable on XMTP. The canMessage method checks each identity's compatibility, returning a response indicating whether each identity can receive messages.

Once you have the verified identities, you can create a new conversation, whether it's a group chat or direct message (DM).

Browser

import { Client } from "@xmtp/browser-sdk";
 
// response is a Map of string (identity) => boolean (is reachable)
const response = await Client.canMessage([bo.identity, caro.identity]);

Create a new group chat

Once you have the verified identities, create a new group chat. The maximum group chat size is 220 members.

Browser

const group = await client.conversations.newGroup(
  [bo.inboxId, caro.inboxId],
  createGroupOptions /* optional */
);

Optimistically create a new group chat

Optimistic group creation enables instant group chat creation and message preparation before adding members and even when offline. This approach prioritizes user experience by allowing immediate interaction with the group chat, while handling the network synchronization in the background when members are added.

Use this method to optimistically create a group chat, which enables a user to create a group chat now and add members later.

The group chat can be created with any number of standard options, or no options. The group chat is stored only in the local storage of the app installation used to create it. In other words, the group chat is visible only to the creator and in the app installation they used to create it.

You can prepare messages for the optimistic group chat immediately using prepareMessage(). As with the group chat itself, these messages are stored locally only.

When you want to add members, you use addMembers() with a list of inbox IDs.

Adding a member will automatically sync the group chat to the network. Once synced, the group chat becomes visible to the added members and across other app installations.

After adding members, you must explicitly call publishMessages() to send any prepared messages to the network.

To learn more about optimistically sending messages using prepareMessage() and publishMessages(), see Optimistically send messages.

Browser

// create optimistic group (stays local)
const optimisticGroup = await alixClient.conversations.newGroupOptimistic();
 
// send optimistic message (stays local)
await optimisticGroup.sendOptimistic("gm");
 
// later, sync the group by adding members
await optimisticGroup.addMembers([boClient.inboxId]);
// or publishing messages
await optimisticGroup.publishMessages();

Create a new DM

Once you have the verified identity, get its inbox ID and create a new DM:

Browser

const group = await client.conversations.newDm(bo.inboxId);

Conversation helper methods

Use these helper methods to quickly locate and access specific conversations—whether by conversation ID, topic, group ID, or DM identity—returning the appropriate ConversationContainer, group, or DM object.

Browser

// get a conversation by its ID
const conversationById = await client.conversations.getConversationById(
  conversationId
);
 
// get a message by its ID
const messageById = await client.conversations.getMessageById(messageId);
 
// get a 1:1 conversation by a peer's inbox ID
const dmByInboxId = await client.conversations.getDmByInboxId(peerInboxId);

Conversation union type

Serves as a unified structure for managing both group chats and DMs. It provides a consistent set of properties and methods to seamlessly handle various conversation types.

React Native: Conversation.ts

Group class

Represents a group chat conversation, providing methods to manage group-specific functionalities such as sending messages, synchronizing state, and handling group membership.

React Native: Group.ts

Dm class

Represents a DM conversation, providing methods to manage one-on-one communications, such as sending messages, synchronizing state, and handling message streams.

React Native: Dm.ts