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-based backup is imported into an installation, all imported conversations start off as inactive, with history visible and in read-only mode. This is as intended by Messaging Layer Security (MLS), which ensures that there is no way to join a conversation without the permission of an existing member. As such, imported conversations will be inactive until the new installation is added to the conversation by an active member. This process happens invisibly and automatically as other members of the group come online and send or receive messages.

This feature includes three core methods:

createArchive creates an encrypted archive.
archiveMetadata reads metadata before import.
importArchive imports an archive into the current installation.

Browser uses in-memory Uint8Array data. Node, Kotlin, and Swift use a file path. Supply a key of at least 32 bytes. The SDK uses the first 32 bytes. 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.

  await 
client: Client<BuiltInContentTypes>
client.
Client<BuiltInContentTypes>.createArchive(path: string, key: Uint8Array, opts?: ArchiveOptions): Promise<void>
Archive application elements to file for later restoration
@param ― path - The file path to save the archive
@param ― key - Encryption key for the archive
@param ― opts - Archive options specifying what to include (defaults to consent and messages)
@returns ― Promise that resolves when the archive is created
createArchive("/path/to/archive.xmtp", 
key: Uint8Array<ArrayBufferLike>
key, {
    
ArchiveOptions.elements: BackupElementSelectionOption[]
elements: [
const enum BackupElementSelectionOption
Selection of what elements to include in a backup
BackupElementSelectionOption.
function (enum member) BackupElementSelectionOption.Consent = "Consent"
Consent],
    
ArchiveOptions.excludeDisappearingMessages: boolean
excludeDisappearingMessages: true,
  });

  const 
const archiveData: Uint8Array<ArrayBufferLike>
archiveData = await 
client: Client<BuiltInContentTypes>
client.
Client<BuiltInContentTypes>.createArchive(key: Uint8Array, opts?: ArchiveOptions): Promise<Uint8Array>
Export archive data to bytes for later restoration
@param ― key - Encryption key for the archive
@param ― opts - Archive options specifying what to include (defaults to consent and messages)
@returns ― Promise that resolves with the archive data as bytes
createArchive(
key: Uint8Array<ArrayBufferLike>
key, {
    
ArchiveOptions.elements: BackupElementSelectionOption[]
elements: [
enum BackupElementSelectionOption
Selection of what elements to include in a backup
BackupElementSelectionOption.
function (enum member) BackupElementSelectionOption.Consent = 1
Consent],
    
ArchiveOptions.excludeDisappearingMessages: boolean
excludeDisappearingMessages: true,
  });

client.createArchive(
    path = "/path/to/archive.xmtp",
    encryptionKey = encryptionKey,
    opts = ArchiveOptions(excludeDisappearingMessages = true)
)

try await client.createArchive(
  path: "/path/to/archive.xmtp",
  encryptionKey: encryptionKey,
  opts: ArchiveOptions(excludeDisappearingMessages: true)
)

Read metadata

archiveMetadata returns startNs, endNs, elements, and exportedAtNs. Browser takes archive bytes and a key. Node, Kotlin, and Swift take a file path and a key.

Import an archive

  await 
client: Client<BuiltInContentTypes>
client.
Client<BuiltInContentTypes>.importArchive(path: string, key: Uint8Array): Promise<void>
Import a previous archive from a file
@param ― path - The file path to the archive
@param ― key - Encryption key for the archive
@returns ― Promise that resolves when the archive is imported
importArchive("/path/to/archive.xmtp", 
key: Uint8Array<ArrayBufferLike>
key);

  await 
client: Client<BuiltInContentTypes>
client.
Client<BuiltInContentTypes>.importArchive(data: Uint8Array, key: Uint8Array): Promise<void>
Import an archive from bytes
@param ― data - The archive data as bytes
@param ― key - Encryption key for the archive
@returns ― Promise that resolves when the archive is imported
importArchive(
data: Uint8Array<ArrayBufferLike>
data, 
key: Uint8Array<ArrayBufferLike>
key);

client.importArchive(path = "/path/to/archive.xmtp", encryptionKey = encryptionKey)

try await client.importArchive(path: "/path/to/archive.xmtp", encryptionKey: encryptionKey)

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

Handle inactive conversations

Attempting to send or sync on an inactive conversation throws a Group is inactive error. Show imported inactive conversations as read-only. An active member or another active installation can add the new installation when it sends a message or syncs the conversation.