Manage XMTP inboxes

jhaaa fix diagrams and references to addresses that use 0x values

With XMTP, a user can have one or more inboxes they use to access their messages. An inbox can have multiple identities associated with it. All messages associated with these identities flow through the one inbox ID and are accessible in any XMTP app.

For an overview of inbox IDs and their future in XMTP, see Identity in XMTP.

The first time someone uses your app with an identity they've never used with any app built with XMTP, your app creates an inbox ID and installation ID associated with the identity. To do this, you create a client for their identity.

The client creates an inbox ID and installation ID associated with the identity. By default, this identity is designated as the recovery identity. A recovery identity will always have the same inbox ID and cannot be reassigned to a different inbox ID.

When you make subsequent calls to create a client for the same identity and a local database is not present, the client uses the same inbox ID, but creates a new installation ID.

You can enable a user to add multiple identities to their inbox. Added identities use the same inbox ID and the installation ID of the installation used to add the identity.

You can enable a user to remove an identity from their inbox. You cannot remove the recovery identity.

Add an identity to an inbox

await client.addAccount(identityToAdd)

Remove an identity from an inbox

await client.removeAccount(recoveryIdentity, identityToRemove)

Revoke installations

🎥 walkthrough: Revoking installations

This video provides a walkthrough of revoking installations, covering the key ideas discussed in this doc. After watching, feel free to continue reading for more details.

Revoke all other installations

You can revoke all installations other than the currently accessed installation.

For example, consider a user using this current installation:

When the user revokes all other installations, the action removes all installations other than the current installation:

await client.revokeAllOtherInstallations(recoveryIdentity)

View the inbox state

Find an inboxId for an identity:

const inboxId = await client.inboxIdFromIdentity(identity)

View the state of any inbox to see the identities, installations, and other information associated with the inboxId.

const state = await client.inboxState(true)
const states = await client.inboxStates(true, [inboxId, inboxId])

InboxState
{
  "recoveryIdentity": "string",
  "identities": [
    {
      "kind": "ETHEREUM",
      "identifier": "string",
      "relyingPartner": "string"
    },
    {
      "kind": "PASSKEY",
      "identifier": "string",
      "relyingPartner": "string"
    }
  ],
  "installations": ["string"],
  "inboxId": "string"
}

FAQ

What happens when a user removes an identity?

Consider an inbox with four associated identities:

If the user removes an identity from the inbox, the identity no longer has access to the inbox it was removed from.

The identity can no longer be added to or used to access conversations in that inbox. If someone sends a message to the identity, the message is not associated with the original inbox. If the user logs in to a new installation with the identity, this will create a new inbox ID.

How is the recovery identity used?

The recovery identity and its signer can be used to sign transactions that remove identities and revoke installations.

For example, Alix can give Bo access to their inbox so Bo can see their groups and conversations and respond for Alix.

If Alix decides they no longer want Bo have access to their inbox, Alix can use their recovery identity signer to remove Bo.

However, while Bo has access to Alix's inbox, Bo cannot remove Alix from their own inbox because Bo does not have access to Alix's recovery identity signer.

If a user created two inboxes using two identities, is there a way to combine the inboxes?

If a user logs in with address 0x62EE...309c and creates inbox 1 and then logs in with address 0xd0e4...DCe8 and creates inbox 2; there is no way to combine inbox 1 and 2.

You can add address 0xd0e4...DCe8 to inbox 1, but both address 0x62EE...309c and 0xd0e4...DCe8 would then have access to inbox 1 only. Address 0xd0e4...DCe8 would no longer be able to access inbox 2.

To help users avoid this state, ensure that your UX surfaces their ability to add multiple identities to a single inbox.

What happens if I remove an identity from an inbox ID and then initiate a client with the private key of the removed identity?

The identity used to initiate a client should be matched to its original inbox ID.

You do have the ability to rotate inbox IDs if a user reaches the limit of 257 identity actions (adding, removing, or revoking identities or installations). Hopefully, users won’t reach this limit, but if they do, inbox IDs have a nonce and can be created an infinite number of times.

However, anytime a new inbox ID is created for an identity, the conversations and messages in any existing inbox ID associated with the identity are lost.

I have multiple identities associated with one inbox ID. If I log in with any one of these identities, does it access that inbox ID, or does it create a new inbox ID?

The identity accesses that inbox ID and does not create a new inbox ID.

For example, let's say that you create a client with an address 0x62EE...309c. Inbox ID 1 is generated from that address 0x62EE...309c.

If you then add a different address 0xd0e4...DCe8 to inbox ID 1, address 0xd0e4...DCe8 is also associated with that inbox ID 1.

If you then log into a new app installation with address 0xd0e4...DCe8, it accesses inbox ID 1 and does not create a new inbox ID.

Once address 0xd0e4...DCe8 has been associated with inbox ID 1, it can then be used to log into inbox ID 1 using a new app installation.

The inverse is also true. Let's say address 0xd0e4...DCe8 was previously used to create and log into inbox ID 2.

If address 0xd0e4...DCe8 is then added as an associated address to inbox ID 1, address 0xd0e4...DCe8 will no longer be able to log into inbox ID 2.

To enable the user of address 0xd0e4...DCe8 to log into inbox ID 2 again, you can use the recovery address for inbox ID 2 to add a different address to inbox ID 2 and have the user use that address access it.

If you are interested in providing this functionality in your app and want some guidance, post to Ideas and Improvements in the XMTP Community Forums.