Consent Management

Manage user consent preferences and control unwanted messages in LibXMTP

Consent management allows users to control which conversations and contacts they interact with. This guide covers setting consent preferences, filtering conversations, and handling blocked users.

Consent States

LibXMTP tracks consent at three levels:

use xmtp_db::consent_record::ConsentState;

pub enum ConsentState {
    Unknown,   // No explicit preference set
    Allowed,   // User has allowed this entity
    Denied,    // User has blocked/denied this entity
}

Consent Types

Consent can be tracked for different entity types:

use xmtp_db::consent_record::ConsentType;

pub enum ConsentType {
    ConversationId,  // Specific group/conversation
    InboxId,         // Entire inbox (all their conversations)
    Address,         // Wallet address
}

Setting Consent

For Conversations

Set consent for a specific group:

use xmtp_db::consent_record::{ConsentState, ConsentType, StoredConsentRecord};

// Allow a conversation
let consent_record = StoredConsentRecord::new(
    hex::encode(&group.group_id),
    ConsentType::ConversationId,
    ConsentState::Allowed,
);

client.set_consent_states(&[consent_record]).await?;

Or use the group helper:

// Update consent directly on the group
group.update_consent_state(ConsentState::Allowed)?;

// Check current state
let state = group.consent_state()?;
assert_eq!(state, ConsentState::Allowed);

For Inbox IDs

Block all conversations from a specific inbox:

let consent_record = StoredConsentRecord::new(
    target_inbox_id.to_string(),
    ConsentType::InboxId,
    ConsentState::Denied,
);

client.set_consent_states(&[consent_record]).await?;

For Addresses

Set consent by wallet address:

let consent_record = StoredConsentRecord::new(
    "0x1234...".to_string(),
    ConsentType::Address,
    ConsentState::Denied,
);

client.set_consent_states(&[consent_record]).await?;

Batch Updates

Update multiple consent preferences at once:

let records = vec![
    StoredConsentRecord::new(
        inbox_id_1.to_string(),
        ConsentType::InboxId,
        ConsentState::Allowed,
    ),
    StoredConsentRecord::new(
        inbox_id_2.to_string(),
        ConsentType::InboxId,
        ConsentState::Denied,
    ),
    StoredConsentRecord::new(
        hex::encode(&group_id),
        ConsentType::ConversationId,
        ConsentState::Allowed,
    ),
];

client.set_consent_states(&records).await?;

Querying Consent

Get Consent State

Check consent for a specific entity:

use xmtp_db::consent_record::ConsentType;

// Check group consent
let state = client.get_consent_state(
    ConsentType::ConversationId,
    hex::encode(&group_id),
).await?;

match state {
    ConsentState::Allowed => println!("Conversation allowed"),
    ConsentState::Denied => println!("Conversation blocked"),
    ConsentState::Unknown => println!("No preference set"),
}

// Check inbox consent
let state = client.get_consent_state(
    ConsentType::InboxId,
    inbox_id.to_string(),
).await?;

Query Groups by Consent

Filter conversations by consent state:

use xmtp_db::group::{GroupQueryArgs, GroupMembershipState};

// Get only allowed conversations
let args = GroupQueryArgs::default()
    .consent_states(Some(vec![ConsentState::Allowed]));

let allowed_groups = client.find_groups(args)?;

// Get blocked conversations
let denied_args = GroupQueryArgs::default()
    .consent_states(Some(vec![ConsentState::Denied]));

let blocked_groups = client.find_groups(denied_args)?;

Default Consent Behavior

Group Creation

When you create a group, consent defaults to Allowed:

let group = client.create_group(None, None)?;

// Consent is automatically set to Allowed
assert_eq!(group.consent_state()?, ConsentState::Allowed);

Receiving Invites

When invited to a group, consent defaults to Unknown:

// User receives a welcome message
client.sync_welcomes().await?;

let groups = client.find_groups(GroupQueryArgs::default())?;
for group in groups {
    let state = group.consent_state()?;
    if state == ConsentState::Unknown {
        println!("New invitation - no consent set yet");
    }
}

Filtering Streams

Consent preferences automatically filter message streams:

Stream Allowed Messages Only

use xmtp_db::consent_record::ConsentState;

// Only receive messages from allowed conversations
let stream = client.stream_all_messages(
    None,  // conversation_type
    Some(vec![ConsentState::Allowed]),  // consent filter
).await?;

while let Some(message) = stream.next().await {
    // Only messages from allowed conversations
    process_message(message);
}

Stream All Conversations

Include both allowed and unknown (new invites):

let stream = client.stream_all_messages(
    None,
    Some(vec![ConsentState::Allowed, ConsentState::Unknown]),
).await?;

Sync with Consent Filtering

Sync only groups matching consent preferences:

// Sync only allowed and unknown groups
let summary = client.sync_all_welcomes_and_groups(
    Some(vec![ConsentState::Allowed, ConsentState::Unknown])
).await?;

println!("Synced {} groups", summary.num_groups_synced);

Device Sync

Consent preferences sync across installations:

// On device 1: Set consent
group.update_consent_state(ConsentState::Denied)?;

// On device 2: Consent is automatically synced
client.sync_welcomes().await?;
let synced_group = client.group(&group.group_id)?;
assert_eq!(synced_group.consent_state()?, ConsentState::Denied);

Consent preferences are synced between your installations via the device sync mechanism. Changes on one device will propagate to other devices.

TypeScript (Node.js) Examples

Set Consent

import { ConsentState, ConsentEntityType } from '@xmtp/node-bindings'

// Allow a conversation
await client.setConsentStates([{
  entityType: ConsentEntityType.GroupId,
  entity: conversation.id(),
  state: ConsentState.Allowed
}])

// Block an inbox
await client.setConsentStates([{
  entityType: ConsentEntityType.InboxId,
  entity: targetInboxId,
  state: ConsentState.Denied
}])

Handling Unwanted Conversations

Best Practices

Consent and Direct Messages

DM consent works the same as groups:

// Create DM (consent defaults to Allowed)
let dm = client.find_or_create_dm(target_inbox_id, None).await?;
assert_eq!(dm.consent_state()?, ConsentState::Allowed);

// Block DM partner
dm.update_consent_state(ConsentState::Denied)?;

// Or block their entire inbox
let consent_record = StoredConsentRecord::new(
    target_inbox_id.to_string(),
    ConsentType::InboxId,
    ConsentState::Denied,
);
client.set_consent_states(&[consent_record]).await?;

Error Handling

use xmtp_db::StorageError;

match group.update_consent_state(ConsentState::Denied) {
    Ok(_) => println!("Consent updated"),
    Err(e) => {
        eprintln!("Failed to update consent: {}", e);
        // Handle error - maybe retry or notify user
    }
}

Next Steps

Database Encryption

Secure your local data with encryption

Managing Groups

Learn more about group management