Build with user consent methods with XMTP
Use the following methods to support user consent preferences 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.
// 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.
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.
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.
// 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.
// 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.
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 toallowed
.
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.