Consent

Consent records what a user wants to hear. A conversation or inbox ID has one of three states. An entity with no record is unknown. The UI locations below are suggested app behavior.

State	Meaning	UI location
unknown	Nobody has decided	Requests
allowed	The user consented	Main inbox
denied	The user refused	Hidden

Consent records are stored locally. When device sync is enabled, device sync copies decisions to the inbox’s other installations. A later consent time wins; at equal times, denied wins over allowed, then unknown.

State changes

Trigger	State
A peer starts a conversation	Usually unknown; an existing DM can inherit its prior state
The user creates a conversation	allowed
The user sends a message	allowed
The app sets consent after accepting or subscribing	allowed
The app sets consent after blocking or unsubscribing	denied
The user is re-added to a group they left	unknown, unless the group names the own inbox as creator

The user’s creation of the conversation with the contact is considered consent. On the current client, a joined group that names the own inbox as creator is also set to allowed. This check uses the creator field; it does not prove which inbox added the user.

The user’s response to the conversation is considered consent.

Sending a message sets the conversation to allowed from any prior state, including denied. Prevent sending in a denied conversation unless the user explicitly reverses the block.

Consent API

Task	Browser, Node	Kotlin, Swift
Read group	(await group.state()).common.consentState	group.state().common.consentState with suspend or try await
Read DM	(await dm.state()).consentState	dm.state().consentState with suspend or try await
Read an entity	client.preferences.consentState(entity)	client.preferences().consentState(entity)
Set conversation	conversation.updateConsentState(state)	conversation.updateConsentState(state)
Set many	client.preferences.setConsentStates(records)	client.preferences().setConsentStates(records)
Stream changes	client.events(filter)	client.events(filter)

For JavaScript, a consent entity is { kind: "conversation", conversationId } or { kind: "inbox", inboxId }. Kotlin uses ConsentEntity.Conversation(id) or ConsentEntity.Inbox(id). Swift uses .conversation(conversationId: id) or .inbox(inboxId: id). A ConsentRecord holds that entity and its state. Swift uses argument labels, such as consentState(entity: entity) and setConsentStates(records: records).

Inbox consent does not automatically set conversation consent. Set the conversation state when the user accepts or blocks a conversation. Consent does not prevent sending. Pass consent filters when listing or reading messages.

The stream reports a ConsentChanged payload with entityKind, entity, and state on Kotlin and Swift. JavaScript wraps this payload in event.consent_changed; its fields are entity_kind, entity, and state.

Batch state changes when possible. A batch commits its final state for each entity in one transaction. Device sync publishes preference changes separately.

Browser

  const stream = await client.events({
    kinds: ["consent.changed"],
    references_own_messages: false,
  });
  const receive = (async () => {
    for await (const event of stream) {
      if (event.kind === "consent.changed") handleConsent(event);
    }
  })();

Node

  const stream = await client.events({
    kinds: ["consent.changed"],
    references_own_messages: false,
  });
  const receive = (async () => {
    for await (const event of stream) {
      if (event.kind === "consent.changed") handleConsent(event);
    }
  })();

Kotlin

client.events(EventFilter(
    kinds = listOf(EventKind.CONSENT_CHANGED),
    groupIds = null,
    contentTypes = null,
    referencesOwnMessages = false,
)).collect { event ->
    if (event is ClientEvent.ConsentChanged) handleConsent(event.consentChanged)
}

Swift

let filter = EventFilter(
  kinds: [.consentChanged], groupIds: nil,
  contentTypes: nil, referencesOwnMessages: false
)
for try await event in try await client.events(filter) {
  if case let .consentChanged(change) = event {
    handleConsent(change)
  }
}

See who added the user

Groups and DMs expose addedByInboxId and creatorInboxId as properties on Browser and Node. Kotlin and Swift expose addedByInboxId() and creatorInboxId() methods. Both values can be absent, for example after restoration. Do not treat a creator field alone as proof that the creator added the user.

Use client events to react to local consent changes. Event listeners do not apply consent filters.