Skip to content
XMTP status

Get started with the XMTP Node SDK

Use the XMTP Node SDK to build agents and other server-side applications that interact with the XMTP network.

For all other server-side applications, including backends for chat inboxes, follow the get started guide below, which provides some quickstart code, as well as a map to building a secure messaging app with XMTP, including support for:

  • End-to-end encrypted direct message and group chat conversations
  • Rich content types (attachments, reactions, replies, and more)
  • Spam-free inboxes using user consent preferences

Quickstart

Node
// 1. Create an EOA or SCW signer.
// Details depend on your app's wallet implementation.
import type { Signer, Identifier, IdentifierKind } from "@xmtp/node-sdk";
 
const signer: Signer = {
  type: "EOA",
  getIdentifier: () => ({
    identifier: "0x...", // Ethereum address as the identifier
    identifierKind: IdentifierKind.Ethereum
  }),
  signMessage: async (message: string): Uint8Array => {
    // typically, signing methods return a hex string
    // this string must be converted to bytes and returned in this function
  },
};
 
// 2. Create the XMTP client
import { Client } from "@xmtp/node-sdk";
import { getRandomValues } from "node:crypto";
 
const dbEncryptionKey = getRandomValues(new Uint8Array(32));
const client = await Client.create(signer, { dbEncryptionKey });
 
// 3. Start a new conversation
const group = await client.conversations.newGroup(
  [bo.inboxId, caro.inboxId],
  createGroupOptions /* optional */
);
 
// 4. Send messages
await group.send("Hello everyone");
 
// 5. List, stream, and sync
// List existing conversations
const allConversations = await client.conversations.list({ consentStates: [ConsentState.Allowed] });
// Stream new messages
const stream = await client.conversations.streamAllMessages(["allowed"]);
 
try {
  for await (const message of stream) {
    // Received a message
  }
} catch (error) {
  console.error(error);
}
// Sync all new welcomes, preference updates, conversations,
// and messages from allowed conversations 
await client.conversations.syncAll(["allowed"]);

🛠️ Phase 0: Explore XMTP developer tools

💬 Phase I: Build core messaging

  1. Create an EOA or SCW signer.

  2. Create an XMTP client.

  3. Check if an identity is reachable on XMTP.

  4. Create a group chat or direct message (DM) conversation.

    With XMTP, "conversation" refers to both group chat and DM conversations.

  5. Send messages in a conversation.

  6. Manage group chat permissions and metadata.

  7. Manage identities, inboxes, and installations.

  8. Be sure to observe rate limits.

📩 Phase II: Manage conversations and messages

  1. List existing conversations from local storage.

  2. Stream new conversations from the network.

  3. Stream new messages from the network.

  4. Sync new conversations from the network.

  5. Sync a specific conversation's messages and preference updates from the network.

💅🏽 Phase III: Enhance the user experience

  1. Implement user consent, which provides a consent value of either unknown, allowed or denied to each of a user's contacts. You can use these consent values to filter conversations. For example:

    • Conversations with allowed contacts go to a user's main inbox
    • Conversations with unknown contacts go to a possible spam tab
    • Conversations with denied contacts are hidden from view.

  2. Support rich content types.

  3. Implement push notifications, if applicable.

🧪 Phase IV: Test and debug