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, React Native, 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,
  });

React Native

  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, React Native, 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,
  );

React Native

  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

Only import archives from a trusted source. Import does not verify message provenance or sender membership, and anyone with the key can forge history under another sender. Legacy repeated-nonce archives have weakened confidentiality and authentication; importing them cannot restore those guarantees.

Browser

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

Node

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

React Native

  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.

React Native files and keys

Use app-accessible native paths for file archives. The app owns file selection, sharing, permissions, and key persistence. Keep archive keys separate from the archive. Archive import does not adopt a legacy database or restore its installation secrets. For pre-8.0.0 storage, follow the React Native upgrade guide.