Backups

Support archive-based backups to give your users an easy and durable way to back up their XMTP conversations, messages, and consent preferences from one app installation and import them into another.

When an archive adds a conversation that is absent from the local database, that conversation starts inactive. Its imported history is visible in read-only mode. Import does not grant MLS membership or provide group secrets. A validated Welcome must add this installation before it can send or decrypt new messages. A conversation that is already in the database keeps its current live state.

This feature includes three operations:

• exportToBytes creates an encrypted archive in memory. Native SDKs also expose exportToFile.
• metadataFromBytes reads metadata before import. Native SDKs also expose metadataFromFile.
• importFromBytes imports an archive into the current installation. Native SDKs also expose importFromFile.

Browser uses in-memory Uint8Array data. Node, Kotlin, and Swift also support file paths. Supply a key of exactly 32 bytes. Other key lengths fail. Store the key separately from the archive.

Create an archive

The options can limit the time range and include messages, consent records, or both. excludeDisappearingMessages defaults to false.

Browser

  const archiveData = await client.archives.exportToBytes(key, {
    elements: ["messages", "consent"],
    excludeDisappearingMessages: true,
  });

Node

  await client.archives.exportToFile("/path/to/archive.xmtp", key, {
    elements: ["messages", "consent"],
    excludeDisappearingMessages: true,
  });

Kotlin

client.archives().exportToFile(
    path = "/path/to/archive.xmtp",
    keyBytes = encryptionKey,
    options = ArchiveOptions(excludeDisappearingMessages = true),
)

Swift

try await client.archives().exportToFile(
  path: "/path/to/archive.xmtp",
  keyBytes: encryptionKey,
  options: ArchiveOptions(excludeDisappearingMessages: true)
)

Read metadata

ArchiveMetadata contains backupVersion, elements, exportedAt, start, and end. The time fields use the SDK Timestamp type. Browser reads metadata from bytes. Node, Kotlin, and Swift can read it from bytes or a file path. Both methods require the encryption key.

Browser

  const metadata = await client.archives.metadataFromBytes(data, key);

Node

  const metadata = await client.archives.metadataFromFile(
    "/path/to/archive.xmtp",
    key,
  );

Kotlin

val metadata = client.archives().metadataFromFile(
    path = "/path/to/archive.xmtp",
    keyBytes = encryptionKey,
)

Swift

let metadata = try await client.archives().metadataFromFile(
  path: "/path/to/archive.xmtp",
  keyBytes: encryptionKey
)

Import an archive

Browser

  await client.archives.importFromBytes(data, key);

Node

  await client.archives.importFromFile("/path/to/archive.xmtp", key);

Kotlin

client.archives().importFromFile(path = "/path/to/archive.xmtp", keyBytes = encryptionKey)

Swift

try await client.archives().importFromFile(path: "/path/to/archive.xmtp", keyBytes: encryptionKey)

The archive import is additive, not destructive: existing messages are preserved, and duplicate messages are ignored.

Handle inactive conversations

Sending to or syncing an imported inactive conversation fails with an inactive-group error. Show its history as read-only. An active member must add this installation. After the SDK processes a valid Welcome, the conversation can become active.