Build a quickstart chat app

Follow this tutorial to run a local XMTP backend and send a message from one client to another.

Each client uses a key pair to create an identity and register it with the backend. This gives the client an inbox ID, which is a stable identifier that other clients send messages to.

You need Docker with Docker Compose. For Browser and Node, you also need Node.js 22.18.0 or later.

1. Start a local backend

Run these commands in a terminal. They create a project directory, download the Compose file, and start PostgreSQL and the XMTP backend:

mkdir xmtp-quickstart && cd xmtp-quickstart
curl -fsSL https://xmtp.org/quickstart/compose.yaml -o compose.yaml
docker compose up -d --wait

The last command returns when the backend is healthy. The backend URL is http://127.0.0.1:5050. Use 127.0.0.1, not localhost: some systems resolve localhost to an IPv6 address that Docker does not forward.

The Compose file

# Local XMTP backend for the quickstart. Do not use it in production:
# it has no authentication and a fixed database password.
#
#   docker compose up -d --wait   start, and wait until the backend is healthy
#   docker compose logs backend   show the backend logs
#   docker compose down           stop, and keep the data
#   docker compose down -v        stop, and delete the data
#
# Clients connect to http://127.0.0.1:5050.
name: xmtp-quickstart

services:
  db:
    image: postgres:18.6
    environment:
      POSTGRES_USER: xmtp
      POSTGRES_PASSWORD: xmtp
      POSTGRES_DB: xmtp
    volumes:
      - db-data:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U xmtp -d xmtp"]
      interval: 1s
      timeout: 3s
      retries: 30

  backend:
    image: ghcr.io/xmtp/backend:8.0.0-rc2
    depends_on:
      db:
        condition: service_healthy
    environment:
      XMTP_DATABASE_URL: postgres://xmtp:xmtp@db:5432/xmtp
      XMTP_CONFIG: |
        [server]
        identifier = "local.xmtp.quickstart"

        [database]
        url = "env:XMTP_DATABASE_URL"
    ports:
      # Loopback only. Change to "5050:5050" to reach it from another device.
      - "127.0.0.1:5050:5050"
    healthcheck:
      test: ["CMD", "/bin/grpc-health-probe", "-addr=127.0.0.1:5050"]
      interval: 1s
      timeout: 5s
      retries: 30

volumes:
  db-data:

This backend has no authentication. Do not expose it outside your computer. See Run the backend for a production configuration.

2. Install the SDK

Use SDK 8.0.0-rc2, which matches the backend image. See Install the XMTP SDK for other package managers.

Create a Vite app in the xmtp-quickstart directory and install the SDK:

npm create vite@latest web -- --template vanilla-ts --no-interactive
cd web
npm install
npm install --save-exact @xmtp/browser-sdk@8.0.0-rc2

In the xmtp-quickstart directory, create an ES module project and install the SDK:

npm init -y
npm pkg set type=module
npm install --save-exact @xmtp/node-sdk@8.0.0-rc2

3. Write the app

The Browser and Node examples come from complete source files. They are checked against the SDK types during the docs build.

Replace the contents of src/main.ts with this code. Each page load creates a new client. A page opened with ?to=<inbox-id> sends one message to that inbox.

import { 
class Client
An XMTP client. Its inputs and results are public values; the binding
Client and the target transport stay private to the package.
Client } from "@xmtp/browser-sdk";

const 
const log: (line: string) => void
log = (
line: string
line: string) => {
  
var document: Document
window.document returns a reference to the document contained in the window.
MDN Reference
document.
Document.body: HTMLElement
The Document.body property represents the  or  node of the current document, or null if no such element exists.
MDN Reference
body.
ParentNode.append(...nodes: (Node | string)[]): void
Inserts nodes after the last child of node, while replacing strings in nodes with equivalent Text nodes.
Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated.
MDN Reference
append(
line: string
line, 
var document: Document
window.document returns a reference to the document contained in the window.
MDN Reference
document.
Document.createElement<"br">(tagName: "br", options?: ElementCreationOptions): HTMLBRElement (+2 overloads)
In an HTML document, the document.createElement() method creates the HTML element specified by localName, or an HTMLUnknownElement if localName isn't recognized.
MDN Reference
createElement("br"));
};

// A new identity and an in-memory database for each page load.
const 
const client: Client
client = await 
class Client
An XMTP client. Its inputs and results are public values; the binding
Client and the target transport stay private to the package.
Client.
Client.create(signer: Signer, options: ClientOptions): Promise<Client>
create(await 
class Client
An XMTP client. Its inputs and results are public values; the binding
Client and the target transport stay private to the package.
Client.
ClientMembers.generateKeys(): Promise<LocalSigningKey>
generateKeys(), {
  
backend?: BackendSource | undefined
backend: { 
url: string
url: "http://127.0.0.1:5050" },
  
storage: StorageOptions
storage: { 
location: StorageLocation
location: "inMemory" },
});
const log: (line: string) => void
log(`Your inbox ID: ${
const client: Client
client.
ClientMembers.inboxId: string
inboxId}`);
const log: (line: string) => void
log(`To message this tab, open ${
var location: Location
The read-only location property of the Window interface returns a Location object with information about the current location of the document.
MDN Reference
location.
Location.origin: string
The origin read-only property of the Location interface returns a string containing the Unicode serialization of the origin of the location's URL.
MDN Reference
origin}/?to=${
const client: Client
client.
ClientMembers.inboxId: string
inboxId}`);

// With ?to=<inbox-id>, send one message to that inbox.
const 
const to: string | null
to = new 
var URLSearchParams: new (init?: string[][] | Record<string, string> | string | URLSearchParams) => URLSearchParams
The URLSearchParams interface defines utility methods to work with the query string of a URL.
MDN Reference
URLSearchParams(
var location: Location
The read-only location property of the Window interface returns a Location object with information about the current location of the document.
MDN Reference
location.
Location.search: string
The search property of the Location interface is a search string, also called a query string, that is a string containing a "?" followed by the parameters of the location's URL. If the URL does not have a search query, this property contains an empty string, "".
MDN Reference
search).
URLSearchParams.get(name: string): string | null
The get() method of the URLSearchParams interface returns the first value associated to the given search parameter.
MDN Reference
get("to");
if (
const to: string | null
to) {
  const 
const dm: Dm
dm = await 
const client: Client
client.
ClientMembers.conversations: Conversations
conversations.
Conversations.createDm(peer: InboxId | PublicIdentity, options?: CreateDmOptions): Promise<Dm>
createDm(
const to: string
to);
  await 
const dm: Dm
dm.
Dm.sendText(text: string, options?: SendOptions): Promise<MessageId>
sendText("Hello from the browser");
}

// The stream also finds new conversations.
for await (const 
const message: Message
message of 
const client: Client
client.
ClientMembers.conversations: Conversations
conversations.
Conversations.streamAllMessages(options?: MessageStreamOptions): MessageStream
streamAllMessages()) {
  if (
const message: Message
message.
Message.content: MessageContent
content.
kind: "text" | "markdown" | "readReceipt" | "reaction" | "attachment" | "remoteAttachment" | "multiRemoteAttachment" | "transactionReference" | "walletSendCalls" | "actions" | "intent" | "groupUpdated" | "leaveRequest" | "deletedMessage" | "reply" | "custom" | "unknown"
kind === "text") {
    const 
const sender: "You" | "Them"
sender = 
const message: Message
message.
MessageFields.senderInboxId: string
senderInboxId === 
const client: Client
client.
ClientMembers.inboxId: string
inboxId ? "You" : "Them";
    
const log: (line: string) => void
log(`${
const sender: "You" | "Them"
sender}: ${
const message: Message
message.
Message.content: {
    readonly kind: "text";
    readonly value: string;
}
content.
value: string
value}`);
  }
}

Create listen.ts. It creates a client, prints its inbox ID, and prints each text message it receives:

import { 
class Client
An XMTP client. Its inputs and results are public values; the binding
Client and the target transport stay private to the package.
Client } from "@xmtp/node-sdk";

// A new identity and an in-memory database. Both are gone when the script stops.
const 
const client: Client
client = await 
class Client
An XMTP client. Its inputs and results are public values; the binding
Client and the target transport stay private to the package.
Client.
Client.create(signer: Signer, options: ClientOptions): Promise<Client>
create(await 
class Client
An XMTP client. Its inputs and results are public values; the binding
Client and the target transport stay private to the package.
Client.
ClientMembers.generateKeys(): Promise<LocalSigningKey>
generateKeys(), {
  
backend?: BackendSource | undefined
backend: { 
url: string
url: 
var process: NodeJS.Process
process.
NodeJS.Process.env: NodeJS.ProcessEnv
The process.env property returns an object containing the user environment.
See environ(7).
An example of this object looks like:
{
  "TERM": "xterm-256color",
  "SHELL": "/usr/local/bin/bash",
  "USER": "maciej",
  "PATH": "~/.bin/:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin",
  "PWD": "/Users/maciej",
  "EDITOR": "vim",
  "SHLVL": "1",
  "HOME": "/Users/maciej",
  "LOGNAME": "maciej",
  "_": "/usr/local/bin/node"
}
It is possible to modify this object, but such modifications will not be
reflected outside the Node.js process, or (unless explicitly requested)
to other Worker threads.
In other words, the following example would not work:
Terminal window
node -e 'process.env.foo = "bar"' &#x26;&#x26; echo $foo
While the following will:
import { env } from 'node:process';

env.foo = 'bar';
console.log(env.foo);
Assigning a property on process.env will implicitly convert the value
to a string. This behavior is deprecated. Future versions of Node.js may
throw an error when the value is not a string, number, or boolean.
import { env } from 'node:process';

env.test = null;
console.log(env.test);
// => 'null'
env.test = undefined;
console.log(env.test);
// => 'undefined'
Use delete to delete a property from process.env.
import { env } from 'node:process';

env.TEST = 1;
delete env.TEST;
console.log(env.TEST);
// => undefined
On Windows operating systems, environment variables are case-insensitive.
import { env } from 'node:process';

env.TEST = 1;
console.log(env.test);
// => 1
Unless explicitly specified when creating a Worker instance,
each Worker thread has its own copy of process.env, based on its
parent thread's process.env, or whatever was specified as the env option
to the Worker constructor. Changes to process.env will not be visible
across Worker threads, and only the main thread can make changes that
are visible to the operating system or to native add-ons. On Windows, a copy of process.env on a Worker instance operates in a case-sensitive manner
unlike the main thread.
@since ― v0.1.27
env.
string | undefined
XMTP_BACKEND_URL ?? "http://127.0.0.1:5050" },
  
storage: StorageOptions
storage: { 
location: StorageLocation
location: "inMemory" },
});
var console: Console
console.
Console.log(...data: any[]): void
The console.log() static method outputs a message to the console.
MDN Reference
log(
  `Listening. In another terminal, run:\n\n  node send.ts ${
const client: Client
client.
ClientMembers.inboxId: string
inboxId}\n`,
);

// The stream also finds new conversations. Press Ctrl+C to stop.
for await (const 
const message: Message
message of 
const client: Client
client.
ClientMembers.conversations: Conversations
conversations.
Conversations.streamAllMessages(options?: MessageStreamOptions): MessageStream
streamAllMessages()) {
  if (
const message: Message
message.
Message.content: MessageContent
content.
kind: "text" | "markdown" | "readReceipt" | "reaction" | "attachment" | "remoteAttachment" | "multiRemoteAttachment" | "transactionReference" | "walletSendCalls" | "actions" | "intent" | "groupUpdated" | "leaveRequest" | "deletedMessage" | "reply" | "custom" | "unknown"
kind === "text") {
    
var console: Console
console.
Console.log(...data: any[]): void
The console.log() static method outputs a message to the console.
MDN Reference
log(`New message: ${
const message: Message
message.
Message.content: {
    readonly kind: "text";
    readonly value: string;
}
content.
value: string
value}`);
  }
}

Create send.ts. It creates a second client and sends one message to the inbox ID you pass to it:

import { 
class Client
An XMTP client. Its inputs and results are public values; the binding
Client and the target transport stay private to the package.
Client } from "@xmtp/node-sdk";

const [
const inboxId: string
inboxId, 
const text: string
text = "Hello from XMTP"] = 
var process: NodeJS.Process
process.
NodeJS.Process.argv: string[]
The process.argv property returns an array containing the command-line
arguments passed when the Node.js process was launched. The first element will
be
execPath
. See process.argv0 if access to the original value
of argv[0] is needed. The second element will be the path to the JavaScript
file being executed. If a program entry point was provided, the second element
will be the absolute path to it. The remaining elements are additional command-line
arguments.
For example, assuming the following script for process-args.js:
import { argv } from 'node:process';

// print process.argv
argv.forEach((val, index) => {
  console.log(`${index}: ${val}`);
});
Launching the Node.js process as:
Terminal window
node process-args.js one two=three four
Would generate the output:
0: /usr/local/bin/node
1: /Users/mjr/work/node/process-args.js
2: one
3: two=three
4: four
@since ― v0.1.27
argv.
Array<string>.slice(start?: number, end?: number): string[]
Returns a copy of a section of an array.
For both start and end, a negative index can be used to indicate an offset from the end of the array.
For example, -2 refers to the second to last element of the array.
@param ― start The beginning index of the specified portion of the array.
If start is undefined, then the slice begins at index 0.
@param ― end The end index of the specified portion of the array. This is exclusive of the element at the index 'end'.
If end is undefined, then the slice extends to the end of the array.
slice(2);
if (!
const inboxId: string
inboxId) throw new 
var Error: ErrorConstructor
new (message?: string, options?: ErrorOptions) => Error (+1 overload)
Error("Usage: node send.ts <inbox-id> [message]");

const 
const client: Client
client = await 
class Client
An XMTP client. Its inputs and results are public values; the binding
Client and the target transport stay private to the package.
Client.
Client.create(signer: Signer, options: ClientOptions): Promise<Client>
create(await 
class Client
An XMTP client. Its inputs and results are public values; the binding
Client and the target transport stay private to the package.
Client.
ClientMembers.generateKeys(): Promise<LocalSigningKey>
generateKeys(), {
  
backend?: BackendSource | undefined
backend: { 
url: string
url: 
var process: NodeJS.Process
process.
NodeJS.Process.env: NodeJS.ProcessEnv
The process.env property returns an object containing the user environment.
See environ(7).
An example of this object looks like:
{
  "TERM": "xterm-256color",
  "SHELL": "/usr/local/bin/bash",
  "USER": "maciej",
  "PATH": "~/.bin/:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin",
  "PWD": "/Users/maciej",
  "EDITOR": "vim",
  "SHLVL": "1",
  "HOME": "/Users/maciej",
  "LOGNAME": "maciej",
  "_": "/usr/local/bin/node"
}
It is possible to modify this object, but such modifications will not be
reflected outside the Node.js process, or (unless explicitly requested)
to other Worker threads.
In other words, the following example would not work:
Terminal window
node -e 'process.env.foo = "bar"' &#x26;&#x26; echo $foo
While the following will:
import { env } from 'node:process';

env.foo = 'bar';
console.log(env.foo);
Assigning a property on process.env will implicitly convert the value
to a string. This behavior is deprecated. Future versions of Node.js may
throw an error when the value is not a string, number, or boolean.
import { env } from 'node:process';

env.test = null;
console.log(env.test);
// => 'null'
env.test = undefined;
console.log(env.test);
// => 'undefined'
Use delete to delete a property from process.env.
import { env } from 'node:process';

env.TEST = 1;
delete env.TEST;
console.log(env.TEST);
// => undefined
On Windows operating systems, environment variables are case-insensitive.
import { env } from 'node:process';

env.TEST = 1;
console.log(env.test);
// => 1
Unless explicitly specified when creating a Worker instance,
each Worker thread has its own copy of process.env, based on its
parent thread's process.env, or whatever was specified as the env option
to the Worker constructor. Changes to process.env will not be visible
across Worker threads, and only the main thread can make changes that
are visible to the operating system or to native add-ons. On Windows, a copy of process.env on a Worker instance operates in a case-sensitive manner
unlike the main thread.
@since ― v0.1.27
env.
string | undefined
XMTP_BACKEND_URL ?? "http://127.0.0.1:5050" },
  
storage: StorageOptions
storage: { 
location: StorageLocation
location: "inMemory" },
});
const 
const dm: Dm
dm = await 
const client: Client
client.
ClientMembers.conversations: Conversations
conversations.
Conversations.createDm(peer: InboxId | PublicIdentity, options?: CreateDmOptions): Promise<Dm>
createDm(
const inboxId: string
inboxId);
await 
const dm: Dm
dm.
Dm.sendText(text: string, options?: SendOptions): Promise<MessageId>
sendText(
const text: string
text);
var console: Console
console.
Console.log(...data: any[]): void
The console.log() static method outputs a message to the console.
MDN Reference
log(`Sent: ${
const text: string
text}`);
await 
const client: Client
client.
Client.end(): Promise<void>
End the client. Messages from it then fail with ClientClosed. Ending a
closed client does nothing, also after its browser worker stopped.
end();

The signer provides identity(), kind(), and sign(request). SDKClient.generateKeys() returns a local signing key that implements these methods. This example creates two temporary clients on the same backend, sends a message from one to the other, and streams messages. Replace the backend URL with a URL that your device can reach.

import android.content.Context
import java.security.SecureRandom
import uniffi.xmtp_sdk.*
import kotlinx.coroutines.NonCancellable
import kotlinx.coroutines.withContext

suspend fun createDemoClient(context: Context, backendUrl: String): SDKClient {
    val signingKey = SDKClient.generateKeys()
    val keyBytes = ByteArray(32).also { SecureRandom().nextBytes(it) }
    return SDKClient.create(
        context = context,
        signer = signingKey,
        options = ClientOptions(
            backend = BackendSource.Options(BackendOptions(url = backendUrl)),
            storage = StorageOptions(StorageLocation.Default, encryptionKey = keyBytes),
        ),
    )
}

suspend fun withDemoClients(
    context: Context,
    backendUrl: String,
    run: suspend (SDKClient, SDKClient) -> Unit,
) {
    val client = createDemoClient(context, backendUrl)
    try {
        val recipient = createDemoClient(context, backendUrl)
        try {
            run(client, recipient)
        } finally {
            withContext(NonCancellable) { recipient.end() }
        }
    } finally {
        withContext(NonCancellable) { client.end() }
    }
}

// Run in a coroutine in your Android Activity.
withDemoClients(applicationContext, "https://xmtp.example.com") { client, recipient ->
    val group = client.conversations.createGroup(listOf(recipient.inboxId()))
    group.sendText("Hello everyone")
    client.conversations.streamAllMessages().collect { message -> println("New message: $message") }
}

The withDemoClients helper ends both clients when its block exits.

Load each client’s stored 32-byte database key before the calls below. Generate a new key securely for a new database, store it securely, and reuse it on reopen. Omitting the key selects unencrypted storage.

import Foundation
import XmtpSdk

func createDemoClient(backendUrl: String, databaseKey: Data) async throws -> SDKClient {
  let signer = await SDKClient.generateKeys()
  return try await SDKClient.create(
    signer: signer,
    options: ClientOptions(
      backend: .options(options: BackendOptions(url: backendUrl)),
      storage: StorageOptions(location: .default, encryptionKey: databaseKey)
    )
  )
}

// Run from an async context, such as a SwiftUI task.
let backendUrl = "https://xmtp.example.com"
let client = try await createDemoClient(backendUrl: backendUrl, databaseKey: clientDatabaseKey)
let recipient = try await createDemoClient(backendUrl: backendUrl, databaseKey: recipientDatabaseKey)

let group = try await client.conversations.createGroup(members: [recipient.inboxId()])
try await group.sendText(text: "Hello everyone", options: nil)

for try await message in try await client.conversations.streamAllMessages() {
  print("New message: \(message)")
}

When you stop the stream, call try await recipient.end() and try await client.end().

4. Run it

Start the development server:

npm run dev

Open the URL that Vite prints, such as http://localhost:5173/. The page shows its inbox ID.
Open the ?to= link from the first page in a second tab. The second tab sends Hello from the browser.
The first tab shows Them: Hello from the browser.

In the first terminal, start the listener:

node listen.ts

It prints a command with its inbox ID. Run that command in a second terminal from the same directory:

node send.ts <inbox-id> "Hello from XMTP"

The first terminal prints New message: Hello from XMTP. Run send.ts again to send more messages. Press Ctrl+C to stop the listener.

How it works

streamAllMessages() delivers messages from every conversation, including conversations that start after the stream opens. By default, it includes allowed and unknown conversations. A conversation that another inbox starts is unknown until you allow it. See Consent.
When the stream opens, it first delivers the messages that arrived while the client was offline.
These examples use randomly generated keys that get thrown away as soon as the process ends, and in-memory databases. Each run is a new inbox. A real app must save and restore its signing key and keep the same database between launches. In Node, pass a 32-byte storage.encryptionKey to encrypt the database.

Stop the backend

Run these commands in the xmtp-quickstart directory:

docker compose down     # stop, and keep the data
docker compose down -v  # stop, and delete the data