Build a quickstart chat app

Follow this tutorial to build a quickstart chat app with XMTP.

When you build your quickstart app, you will use a key pair to create an identity and register it with XMTP. This gives you an inbox ID, which is a stable identifier that serves as the destination for your messages.

1. Install the SDK

Follow Install the XMTP SDK to install SDK 8.0.0-rc1. From your app directory, install the package for your platform:

npm install --save-exact @xmtp/browser-sdk@8.0.0-rc1

npm install --save-exact @xmtp/node-sdk@8.0.0-rc1

2. Create a signer and client

The signer provides identity(), kind(), and sign(request). Its sign method returns a Signature with the raw signature bytes. The SDK’s Client.generateKeys() (SDKClient.generateKeys() in Kotlin and Swift) returns a local signing key that implements these methods. For a persistent account, save and restore the private key before opening the client. The examples below create temporary accounts. The backend URL is required. Use the URL of your running backend. These examples create temporary identities for testing. Do not use their key lifecycle in a production app: store the signer key and database encryption key securely and reuse them with the same database on later launches.

The Browser and Node blocks come from complete source files. They are checked against the SDK types during the docs build. The mobile examples create a second client so that the message recipient is registered on the same backend.

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

// Use a new signer and an in-memory database for this local test.
const 
const signer: LocalSigningKey
signer = 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();
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(
const signer: LocalSigningKey
signer, {
  
backend?: BackendSource | undefined
backend: { 
url: string
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("Your inbox ID:", 
const client: Client
client.
ClientMembers.inboxId: string
inboxId);

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

// Use a new signer and an in-memory database for this local test.
const 
const signer: LocalSigningKey
signer = 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();
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(
const signer: LocalSigningKey
signer, {
  
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",
    
encryptionKey?: Uint8Array<ArrayBufferLike> | undefined
encryptionKey: 
var crypto: Crypto
MDN Reference
crypto.
Crypto.getRandomValues<Uint8Array<ArrayBuffer>>(array: Uint8Array<ArrayBuffer>): Uint8Array<ArrayBuffer>
The Crypto.getRandomValues() method lets you get cryptographically strong random values. The array given as the parameter is filled with random numbers (random in its cryptographic meaning).
MDN Reference
getRandomValues(new 
var Uint8Array: Uint8ArrayConstructor
new (length: number) => Uint8Array<ArrayBuffer> (+6 overloads)
Uint8Array(32)),
  },
});
var console: Console
console.
Console.log(...data: any[]): void
The console.log() static method outputs a message to the console.
MDN Reference
log("Your inbox ID:", 
const client: Client
client.
ClientMembers.inboxId: string
inboxId);

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

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)

3. Send a message

Create a conversation and send a text message. For Browser and Node, use the inbox ID printed by a second running client on the same backend. Put the Kotlin send and stream operations in the withDemoClients block. For Swift, use the recipient client from the preceding step.

const 
const recipientInboxId: string | null
recipientInboxId = 
var window: Window & typeof globalThis
The window property of a Window object points to the window object itself.
MDN Reference
window.
function prompt(message?: string, _default?: string): string | null
window.prompt() instructs the browser to display a dialog with an optional message prompting the user to input some text, and to wait until the user either submits the text or cancels the dialog.
MDN Reference
prompt("Recipient inbox ID");
if (!
const recipientInboxId: string | null
recipientInboxId) throw new 
var Error: ErrorConstructor
new (message?: string, options?: ErrorOptions) => Error (+1 overload)
Error("Enter a recipient inbox ID");
const 
const group: Group
group = await 
const client: Client
client.
ClientMembers.conversations: Conversations
conversations.
Conversations.createGroup(members: Array<InboxId> | Array<PublicIdentity>, options?: CreateGroupOptions): Promise<Group>
createGroup([
const recipientInboxId: string
recipientInboxId]);
await 
const group: Group
group.
Group.sendText(text: string, options?: SendOptions): Promise<MessageId>
sendText("Hello everyone");

const 
const recipientInboxId: string | undefined
recipientInboxId = 
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_RECIPIENT_INBOX_ID;
if (!
const recipientInboxId: string | undefined
recipientInboxId) throw new 
var Error: ErrorConstructor
new (message?: string, options?: ErrorOptions) => Error (+1 overload)
Error("Set XMTP_RECIPIENT_INBOX_ID");
const 
const group: Group
group = await 
const client: Client
client.
ClientMembers.conversations: Conversations
conversations.
Conversations.createGroup(members: Array<InboxId> | Array<PublicIdentity>, options?: CreateGroupOptions): Promise<Group>
createGroup([
const recipientInboxId: string
recipientInboxId]);
await 
const group: Group
group.
Group.sendText(text: string, options?: SendOptions): Promise<MessageId>
sendText("Hello everyone");

val group = client.conversations.createGroup(listOf(recipient.inboxId()))
group.sendText("Hello everyone")

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

Sending a message stores it locally and publishes it to the backend. Update your UI from the message stream or query the conversation’s messages. See optimistic sending to show a message before publication completes.

4. Stream messages

Use client.conversations.streamAllMessages() in each SDK to receive messages. Use syncAll to fetch welcomes and messages in the selected conversations. The JavaScript examples select allowed conversations; allow an incoming conversation before you expect its messages in that stream. See Consent.

const 
const stream: MessageStream
stream = 
const client: Client
client.
ClientMembers.conversations: Conversations
conversations.
Conversations.streamAllMessages(options?: MessageStreamOptions): MessageStream
streamAllMessages({
  
consentStates?: readonly ConsentState[] | undefined
consentStates: ["allowed"],
});
const 
const receive: Promise<void>
receive = (async () => {
  for await (const 
const message: Message
message of 
const stream: MessageStream
stream) 
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);
})();
await 
const client: Client
client.
ClientMembers.conversations: Conversations
conversations.
Conversations.syncAll(consentStates: Array<ConsentState> | undefined): Promise<GroupSyncSummary>
syncAll(["allowed"]);
// Call stream.return() and await receive when you stop the stream.

const 
const stream: MessageStream
stream = 
const client: Client
client.
ClientMembers.conversations: Conversations
conversations.
Conversations.streamAllMessages(options?: MessageStreamOptions): MessageStream
streamAllMessages({
  
consentStates?: readonly ConsentState[] | undefined
consentStates: ["allowed"],
});
const 
const receive: Promise<void>
receive = (async () => {
  for await (const 
const message: Message
message of 
const stream: MessageStream
stream) 
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);
})();
await 
const client: Client
client.
ClientMembers.conversations: Conversations
conversations.
Conversations.syncAll(consentStates: Array<ConsentState> | undefined): Promise<GroupSyncSummary>
syncAll(["allowed"]);
// Call stream.return() and await receive when you stop the stream.

client.conversations.syncAll(null)
client.conversations.streamAllMessages().collect { message ->
    println("New message: $message")
}

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

When you stop the JavaScript example, call await stream.return(), await receive, then call await client.end(). On mobile, stop the message stream and end both clients. The Kotlin helper does this when its block exits; use try await recipient.end() and try await client.end() in Swift.