Send and list messages with XMTP

The message payload can be a plain string, but you can configure custom 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.

JavaScript

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.

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

React

import { useSendMessage } from "@xmtp/react-sdk";
import type { Conversation } from "@xmtp/react-sdk";
import { useCallback, useState } from "react";

export const SendMessage: React.FC<{ conversation: CachedConversation }> = ({
  conversation,
}) => {
  const [peerAddress, setPeerAddress] = useState("");
  const [message, setMessage] = useState("");
  const [isSending, setIsSending] = useState(false);
  const { sendMessage } = useSendMessage();

  const handleAddressChange = useCallback(
    (e: ChangeEvent<HTMLInputElement>) => {
      setPeerAddress(e.target.value);
    },
    [],
  );

  const handleMessageChange = useCallback(
    (e: ChangeEvent<HTMLInputElement>) => {
      setMessage(e.target.value);
    },
    [],
  );

  const handleSendMessage = useCallback(
    async (e: React.FormEvent) => {
      e.preventDefault();
      if (peerAddress && isValidAddress(peerAddress) && message) {
        setIsLoading(true);
        await sendMessage(conversation, message);
        setIsLoading(false);
      }
    },
    [message, peerAddress, sendMessage],
  );

  return (
    <form onSubmit={handleSendMessage}>
      <input
        name="addressInput"
        type="text"
        onChange={handleAddressChange}
        disabled={isSending}
      />
      <input
        name="messageInput"
        type="text"
        onChange={handleMessageChange}
        disabled={isSending}
      />
    </form>
  );
};

Optimistic sending with React

When a user sends a message with XMTP, they might experience a slight delay between sending the message and seeing their sent message display in their app UI.

Typically, the slight delay is caused by the app needing to wait for the XMTP network to finish processing the message before the app can display the message in its UI.

The local-first architecture of the React SDK automatically includes optimistic sending, which immediately displays the sent message in the sender’s UI while processing the message in the background. Optimistic sending provides the sender with immediate feedback and enables them to continue messaging without waiting for their previous message to finish processing.

Messages in the sending state have their isSending property set to true.

Handle messages that fail to send with React

If a message fails to complete the sending process, you must provide an error state that alerts the user and enables them to either resend the message or cancel sending the message.

While in this unsent state, the message remains in its original location in the user’s conversation flow, with any newer sent and received messages displaying after it.

If the user resends the message, the message moves into the most recently sent message position in the conversation. Once it successfully sends, it remains in that position.

If the user cancels sending the message, the message is removed from the conversation flow.

Messages that fail to send have their hasSendError property set to true.

Resend a failed message

Use the resendMessage function from the useResendMessage hook to resend a failed message.

const { resendMessage } = useResendMessage();

// resend the message
resendMessage(failedMessage);

Kotlin

val conversation =
    client.conversations.newConversation("0x3F11b27F323b62B159D2642964fa27C46C841897")

conversation.send(text = "Hello world")

Swift

let conversation = try await client.conversations.newConversation(
  with: "0x3F11b27F323b62B159D2642964fa27C46C841897")
try await conversation.send(content: "Hello world")

Dart

var convo = await client.newConversation("0x...");
await client.sendMessage(convo, 'gm');

React Native

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

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

React

import { useCallback } from "react";
import { useMessages } from "@xmtp/react-sdk";
import type { CachedConversation } from "@xmtp/react-sdk";

export const Messages: React.FC<{
  conversation: CachedConversation;
}> = ({ conversation }) => {
  // error callback
  const onError = useCallback((err: Error) => {
    // handle error
  }, []);

  // messages callback
  const onMessages = useCallback((msgs: DecodedMessage[]) => {
    // do something with messages
  }, []);

  const { error, messages, isLoading } = useMessages(conversation, {
    onError,
    onMessages,
  });

  if (error) {
    return "An error occurred while loading messages";
  }

  if (isLoading) {
    return "Loading messages...";
  }

  return (
    ...
  );
};

Kotlin

for (conversation in client.conversations.list()) {
    val messagesInConversation = conversation.messages()
}

Swift

for conversation in client.conversations.list() {
  let messagesInConversation = try await conversation.messages()
}

Dart

// Only show messages from the last 24 hours.
var messages = await alice.listMessages(convo,
    start: DateTime.now().subtract(const Duration(hours: 24)));

React Native

for (const conversation of await xmtp.conversations.list()) {
  const messagesInConversation = await conversation.messages(before: new Date(
    new Date().setDate(new Date().getDate() - 1)), after: new Date())
}

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

React

Automatically handled by the SDK

Kotlin

Call conversation.messages(limit: Int, before: Date) to return the specified number of messages sent before that time.

val conversation =
    client.conversations.newConversation("0x3F11b27F323b62B159D2642964fa27C46C841897")

val messages = conversation.messages(limit = 25)
val nextPage = conversation.messages(limit = 25, before = messages[0].sent)

Swift

Call conversation.messages(limit: Int, before: Date), which will return the specified number of messages sent before that time.

let conversation = try await client.conversations.newConversation(
  with: "0x3F11b27F323b62B159D2642964fa27C46C841897")

let messages = try await conversation.messages(limit: 25)
let nextPage = try await conversation.messages(limit: 25, before: messages[0].sent)

Dart

Specify limit and end, which will return the specified number of messages sent before that time.

var messages = await alice.listMessages(convo, limit: 10);
var nextPage = await alice.listMessages(
    convo, limit: 10, end: messages.last.sentAt);

React Native

const conversation = await xmtp.conversations.newConversation(
  '0x3F11b27F323b62B159D2642964fa27C46C841897'
)

for await (const page of conversation.messages(limit: 25)) {
  for (const msg of page) {
    // Breaking from the outer loop will stop the client from requesting any further pages
    if (msg.content === 'gm') {
      return
    }
    console.log(msg.content)
  }
}

Note on Group Chats

The methods for sending and listing messages, as well as handling unsupported content types, are applicable to both one-on-one and group conversations within XMTP. This means you can use the same approach to manage messages in group chats as you would in individual conversations.

For additional information on group chat-specific features, such as managing group members or listening for new messages in a group chat, please see the Group Chats documentation.

Handle an unsupported content type error

As more custom and standards-track content types enter the XMTP ecosystem, your app might receive a content type your app doesn't support. This could crash your app.

JavaScript

To avoid crashing your app, code your app to detect, log, and handle the error. For example:

const codec = xmtp.codecFor(content.contentType);
if (!codec) {
  const fallback = `missing codec for content type "${content.contentType.toString()}"`;
  throw new Error(fallback);
}

React

// If you wish to display an unsupported content type, there’s a contentFallback
// property that may include a useful string. However, it is recommended that
// you manually process unsupported content types.
import { ContentTypeId } from "@xmtp/xmtp-js";
import { ContentTypeAttachment } from "@xmtp/content-type-remote-attachment";

const MessageContent = ({ message }) => {
  if (
    message.content === undefined &&
    ContentTypeId.fromString(message.contentType).sameAs(ContentTypeAttachment)
  ) {
    return "This message contains an attachment, which is not supported by this client.";
  }
};

Kotlin

Code sample coming soon

Swift

Code sample coming soon

Dart

Code sample coming soon

React Native

if(/*Not supported content type*/){
  return message?.fallback ? (
    message?.fallback
  ) : (
    <div style={styles.RenderedMessage}>"Message not supported"</div>
  );
}