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.

You might want to consider optimistically sending messages.

JavaScript

const conversation = await xmtp.conversations.newConversation(
  "0x3F11b27F323b62B159D2642964fa27C46C841897",
);
await conversation.send("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');

Kotlin

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

conversation.send(text = "Hello world")

React

import { useSendMessage } from "@xmtp/react-sdk";

const sendMessage = useSendMessage(conversation);

await sendMessage(message);

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

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

Kotlin

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

React

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

const [conversation, setConversation] = useState(null);
const { messages } = useMessages(conversation);

useEffect(() => {
  if (messages) {
    console.log("Loaded message history:", messages.length);
  }
}, [messages]);

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

Call conversation.messagesPaginated(), which will return an AsyncGenerator yielding one page of results at a time. conversation.messages() uses this under the hood internally to gather all messages.

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

for await (const page of conversation.messagesPaginated({ pageSize: 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);
  }
}

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

Kotlin

Call conversation.messages(limit: Int, before: Date), which will 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)

React

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

const { error, isLoading, messages, next } = useMessages(
  conversation,
  options: {
    limit: 20,
  },
);
const handleClick = useCallback(() => {
  // fetch next page of messages
  next();
}, [next]);


return (

    <button type="button" onClick={handleClick}>
      Load more messages
    </button>

);

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

Decode a single message

You can decode a single Envelope from XMTP using the decode method:

Swift

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

// Assume this function returns an Envelope that contains a message for the above conversation
let envelope = getEnvelopeFromXMTP()

let decodedMessage = try conversation.decode(envelope)

Kotlin

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

// Assume this function returns an Envelope that contains a message for the above conversation
val envelope = getEnvelopeFromXMTP()

val decodedMessage = conversation.decode(envelope)