Send and list messages with XMTP

The message payload can be a plain string, but you can also support other content types. To learn more, see Content types.

Send messages

To send a message, the recipient must have already started their client at least once and consequently advertised their key bundle on the network.

Messages are limited to just short of 1MB (1048214 bytes). Use remote attachments to support larger messages.

TypeScript

const conversation = await xmtp.conversations.newConversation(
  "0x3F11b27F323b62B159D2642964fa27C46C841897",
);
await conversation.send("Hello world");

You might want to consider optimistically sending messages. This way, the app will not have to wait for the network to process the message first. Optimistic sending is especially useful for mobile apps where the user might have a spotty connection, making the app continue to run with multiple threads.

TypeScript

// standard (string) message
const preparedTextMessage = await conversation.prepareMessage(messageText);
// After preparing an optimistic message, use its `send` method to send it.
try {
  preparedTextMessage.send();
} catch (e) {
  // handle error, enable canceling and retries (see below)
}

List messages in a conversation

You can receive the complete message history in a conversation.

JavaScript

for (const conversation of await xmtp.conversations.list()) {
  // All parameters are optional and can be omitted
  const opts = {
    // Only show messages from last 24 hours
    startTime: new Date(new Date().setDate(new Date().getDate() - 1)),
    endTime: new Date(),
  };
  const messagesInConversation = await conversation.messages(opts);
}

List messages in a conversation with pagination

If a conversation has a lot of messages, it's more performant to retrieve and process the messages page by page instead of handling all of the messages at once.

JavaScript

Automatically handled by the SDK

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 contentFallback property, which offers a descriptive string representing the content type's expected value. It's important to note that content fallbacks are immutable and are predefined in the content type specification. In instances where contentFallback 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.

JavaScript

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