List, stream, and sync conversations and messages

List existing group chats or DMs

Get a list of existing group chats or DMs in the local database. By default, the conversations are listed in descending order by their lastMessage created at value. If a conversation does not contain any messages, the conversation is ordered by its createdAt value.

Browser

const allConversations = await client.conversations.list();
const allGroups = await client.conversations.listGroups();
const allDms = await client.conversations.listDms();

Stream all group chats and DMs

Listens to the network for new group chats and DMs. Whenever a new conversation starts, it triggers the provided callback function with a ConversationContainer object. This allows the client to immediately respond to any new group chats or DMs initiated by other users.

Node

const stream = await client.conversations.stream();
// to stream only groups, use `client.conversations.streamGroups()`
// to stream only dms, use `client.conversations.streamDms()`
 
try {
  for await (const conversation of stream) {
    // Received a conversation
  }
} catch (error) {
  // log any stream errors
  console.error(error);
}

Stream all group chat and DM messages

Listens to the network for new messages within all active group chats and DMs. Whenever a new message is sent to any of these conversations, the callback is triggered with a DecodedMessage object. This keeps the inbox up to date by streaming in messages as they arrive.

Node

// stream all messages from all conversations
const stream = await client.conversations.streamAllMessages();
 
// stream only group messages
const stream = await client.conversations.streamAllGroupMessages();
 
// stream only dm messages
const stream = await client.conversations.streamAllDmMessages();
 
try {
  for await (const message of stream) {
    // Received a message
  }
} catch (error) {
  // log any stream errors
  console.error(error);
}

Sync

🎥 walkthrough: Syncing

This video provides a walkthrough of syncing, covering the key ideas discussed in this doc. After watching, feel free to continue reading for more details.

Sync conversation

Get all new messages and group updates (name, description, etc.) for a specific conversation from the network.

Browser

await client.conversation.sync();

Sync conversations

Get any new group chat or DM conversations from the network.

Browser

await client.conversations.sync();

Sync all new conversations, messages, and updates

Sync all new group chat and DM conversations, messages, and installation-related updates (consent states, HMAC keys, etc.) from the network. We recommend that you run this sync in the background and call it more frequently than not.

Browser

await client.conversations.syncAll();

Handle unsupported content types

As more custom and standards-track content types are introduced into the XMTP ecosystem, your app may encounter content types it does not support. This situation, if not handled properly, could lead to app crashes.

Each message is accompanied by a fallback property, which offers a descriptive string representing the content type's expected value. It's important to note that fallbacks are immutable and are predefined in the content type specification. In instances where fallback is undefined, such as read receipts, it indicates that the content is not intended to be rendered. If you're venturing into creating custom content types, you're provided with the flexibility to specify a custom fallback string. For a deeper dive into this, see Build custom content types.

Browser

const codec = client.codecFor(content.contentType);
if (!codec) {
  /*Not supported content type*/
  if (message.fallback !== undefined) {
    return message.fallback;
  }
  // Handle other types like ReadReceipts which are not meant to be displayed
}