Skip to content

Get started building with XMTP

XMTP (Extensible Message Transport Protocol) is the largest and most secure decentralized messaging network. XMTP is open and permissionless, empowering any developer to build end-to-end encrypted 1:1, group, and agent messaging experiences, and more.

To learn more, see Why build with XMTP?.

Ways to build with XMTP

Whether you're building a standalone chat app or adding messaging to an existing app, the integration steps are the same and the phases below apply to both.

The main difference is how you connect XMTP to your existing systems:

  • Signer: If your app already has wallet-based authentication, you can reuse that signer with XMTP. No extra login step needed. If your app doesn't use wallets, you can generate a key pair for each user behind the scenes. See Create a signer.

  • Client lifecycle: For standalone chat apps, you typically create the XMTP client at app launch. For embedded chat, you can choose to create it only when the user opens the chat feature for the first time.

  • Identity mapping: If your app has existing users, you'll want to map each user to an XMTP inbox ID. You can store this mapping in your backend and use canMessage to check if other users in your app are reachable on XMTP.

🛠️ Phase 0: Explore XMTP developer tools

  • Pick your SDK:

    BrowserNodeReact NativeAndroidiOS

  • To make it easier for you to build with XMTP using LLMs and coding assistants, we offer two AI-ready solutions:

    • A docs MCP server
    • Use case-based llms.txt files

    To learn more, see Use XMTP documentation with AI coding assistants.

  • Use xmtp.chat, the official web chat app for developers, to interact with and test your app

  • Run a local XMTP node for development and testing.

💬 Phase I: Build core messaging

  1. Create a signer.

  2. Create an XMTP client. Be sure to set the appVersion client option.

  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