Skip to content
Dev support

Enable history sync for apps built with XMTP

Enable the history sync feature to give your users a way to sync decrypted historical data from an existing app installation to a new app installation.

This historical data includes:

  • Conversations
  • Conversation messages
  • Consent state
  • HMAC keys (for push notifications)

History sync enables your users pick up conversations where they left off, regardless of the app installation they use. All they need is a pre-existing and online app installation to provide the data.

Enable history sync

History sync is enabled by default and runs automatically. When creating a client, the historySyncUrl client option is dynamically set to a default history sync server URL based on your env client option setting.

  • When env is set to dev, the historySyncUrl is set to https://message-history.dev.ephemera.network/
  • When env is set to production, the historySyncUrl is set to https://message-history.production.ephemera.network

These default servers are managed and operated by Ephemera, a steward of the development and adoption of XMTP.

You can choose to run your own server and set the historySyncUrl to your server's URL.

How history sync works

When your app initializes an XMTP client and a historySyncUrl client option is present, history sync automatically triggers an initial sync request and creates an encrypted payload.

History sync then uploads the payload, sends a sync reply, and pulls all conversation state history into the new app installation, merging it with the existing app installations in the sync group.

Ongoing updates to history are streamed automatically. Updates, whether for user consent preferences or messages, are sent across the sync group, ensuring all app installations have up-to-date information.

History syncs are accomplished using these components:

  • Sync group
  • Sync worker
  • History server

Sync group

A sync group is a special Messaging Layer Security group that includes all of the user’s devices. The sync group is used to send serialized sync messages across the user's devices. The sync group is filtered out of most queries by default so they don’t appear in the user’s inbox.

Sync worker

A sync worker is a spawned background worker that listens for sync events, and processes them accordingly. This worker:

  • Emits and updates consent
  • Creates and consumes archive payloads for and from other devices
  • Keeps preferences synced across devices

History server

A history server acts as a bucket that holds encrypted sync payloads. The URL location of these payloads and the password (cipher encryption key) to decrypt these payloads is sent over the sync group for the recipient to decrypt.

FAQ

A user logged into a new app installation and doesn't see their conversations. What's going on?

A debounce feature checks for new app installations, at most, once every 30 minutes. To circumvent the cool-down timer, send a message using a pre-existing app installation.

Once this issue is resolved, conversations will appear almost instantly.

A user logged into a new app installation and sees their conversations, but no messages. What's going on?

Ensure that you've initiated a call to sync messages and that the pre-existing app installation is online to receive the sync request, process and encrypt the payload, upload it to the history server, and send a sync reply message to the new app installation.

I called a sync method (messages, consent state, or conversations), but nothing is happening. What's going on?

After requesting a sync for one app installation, ensure that the pre-existing app installation is online to receive the sync request.