Support spam-free inboxes with XMTP user consent methods

Use the following user consent methods to support spam-free inboxes in your app built with XMTP.

Deny or allow a contact

To enable your user to deny or allow a contact, call the following methods. Note that these functions accept lists, so you can do batch requests.

JavaScript

// from the client
await client.contacts.allow([address1, address2]);
await client.contacts.deny([address1, address2]);
 
// from a conversation
await conversation.allow();
await conversation.deny();

Refresh the consent list

To ensure that you’re using the latest consent preferences, make sure to refresh the consent list from the network. Perform the refresh just in case the consent preference has changed on a different device, for example.

refreshConsentList() returns the history of all consent entries.

JavaScript

await client.contacts.refreshConsentList();

Get the consent list

Load the consent list from a specific time. If no time is specified, it loads the consent list from the last time the refresh was made.

JavaScript

await client.contacts.loadConsentList(/* Optional: lastSyncedDate */);

Check if a contact is denied or allowed

Call the following methods to check if a contact is denied or allowed.

JavaScript

// from the client
const isAllowed = client.contacts.isAllowed(address);
const isDenied = client.contacts.isDenied(address);
 
// from a conversation
const isAllowed = conversation.isAllowed;
const isDenied = conversation.isDenied;

Get a conversation’s consent preference

When loading a list of conversations, take into account its consent preference. You can get the consentState directly from the conversation.

JavaScript

// from the client
const consentState = client.contacts.consentState(peerAddress);
 
// from a conversation
const consentState = conversation.consentState;
 
// consentState can be 'allowed', 'denied', or 'unknown'

Stream the consent list

This section provides an example of how to stream the consent list. The code snippet below demonstrates how to create a new conversation and then stream the consent list, logging each action to the console.

JavaScript

const aliceStream = await aliceClient.contacts.streamConsentList();
for await (const action of aliceStream) {
  // Each action indicates the address and if it's allowed or denied
}
await aliceStream.return();

Synchronize user consent preferences

All apps that use the user consent feature must adhere to the logic described in this section to keep the consent list on the network synchronized with local app user consent preferences, and vice versa.

Do not update the consent list on the network except in the scenarios described below.

Update a consent preference in the consent list on the network in the following scenarios only:

A user explicitly denies a contact. For example, the user blocks, unsubscribes from, or disables notifications for the contact. The app should update the consent preference in the consent list to denied.
A user explicitly allows a contact. For example, the user allows, subscribes to, or enables notifications for the contact. The app should update the consent preference in the consent list to allowed.
An existing conversation has an unknown consent preference, but a legacy consent preference in the local database exists. The app should update the consent preference in the consent list to match the legacy local content preference.
An existing conversation has an unknown consent preference, but has an existing response from the user. The app should update the consent preference in the consent list to allowed.

The following diagram illustrates the detailed logic for how user consent preferences are set in an app and in the consent list on the XMTP network.