Per-conversation notification controls

Decision and scope#

Version one is a simple two-state preference: Notifications on or Notifications off. It is stored per user and per Claire conversation, so a mute set on iPhone also applies on desktop and future devices. The preference affects only new-message push notifications; messages still arrive, increment the unread count, appear in search, and remain available in the inbox.

Product experience#

Conversation settings

Notifications
  [bell] Notifications                         [On | Off]
  Receive Claire alerts for new messages in this conversation.

Relationship memory
  …

Notification eligibility and precedence#

Delivery is allowed only after all applicable controls allow it. A per-conversation setting narrows delivery; it never overrides a global, device, operating-system, or presence suppression.

Incoming message
  → Ignore if it is sent by the account owner
  → Account-level notifications enabled?             no → suppress: account_disabled
  → Message notifications preference enabled?         no → suppress: messages_disabled
  → Conversation notifications enabled?               no → suppress: conversation_muted
  → Device enabled and a provider token is valid?     no → no delivery candidate
  → Quiet hours on that device?                       yes → suppress: quiet_hours
  → Device is actively viewing this conversation?     yes → suppress: active_chat
  → Queue provider delivery and track the receipt

Badge counts continue to use the user's unread total, including muted conversations. A muted conversation is intentionally not a hidden or archived conversation.

Data model and API#

CREATE TABLE public.conversation_notification_preferences (
  user_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
  chat_id UUID NOT NULL REFERENCES public.chats(id) ON DELETE CASCADE,
  notifications_enabled BOOLEAN NOT NULL DEFAULT TRUE,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  PRIMARY KEY (user_id, chat_id),
  CONSTRAINT conversation_notification_preferences_chat_owner
    FOREIGN KEY (chat_id, user_id) REFERENCES public.chats(id, user_id)
);

CREATE INDEX conversation_notification_preferences_lookup
  ON public.conversation_notification_preferences (user_id, chat_id)
  WHERE notifications_enabled = FALSE;

ALTER TABLE public.conversation_notification_preferences ENABLE ROW LEVEL SECURITY;
CREATE POLICY "Users manage their conversation notification preferences"
  ON public.conversation_notification_preferences
  FOR ALL USING (auth.uid() = user_id) WITH CHECK (auth.uid() = user_id);

type ConversationNotificationPreference = {
  user_id: string;
  chat_id: string;
  notifications_enabled: boolean;
  updated_at: string;
};

await supabase.from('conversation_notification_preferences').upsert(
  { user_id: user.id, chat_id, notifications_enabled: enabled, updated_at: new Date().toISOString() },
  { onConflict: 'user_id,chat_id' },
);

const { data: conversationPreference } = await supabase
  .from('conversation_notification_preferences')
  .select('notifications_enabled')
  .eq('user_id', event.userId)
  .eq('chat_id', event.chatId)
  .maybeSingle();

if (conversationPreference?.notifications_enabled === false) {
  return await recordSuppressedDeliveries({
    event, devices, reason: 'conversation_muted',
  });
}

Implementation plan#

Privacy and safety#

• The preference is account metadata, not message content.
• Push payload content is constructed only after the conversation eligibility check passes.
• Operational logs, metrics, traces, alerting, and the Operations Console record only the suppression reason and aggregate platform counters.
• Do not store contact names, message previews, device tokens, or raw provider receipts in the preference or related telemetry.
• Deletion of the conversation or account removes the preference through database cascades; backups follow the existing deletion and retention policy.

Verification and acceptance criteria#

1. With global notifications on, turn one conversation off and confirm its next inbound message creates no Expo/APNs submission while another conversation still notifies.
2. Confirm muted messages continue to sync, increment unread count, affect the app badge, and are visible in the inbox.
3. Turn the same conversation on from one device; confirm the next inbound message is eligible on another registered device.
4. Confirm global disable, quiet hours, invalid token, and active-chat suppression still win over the conversation setting.
5. Confirm a missing preference row is treated as on for every pre-existing conversation.
6. Run server tests for eligibility order, idempotent suppressed delivery rows, and no provider call when conversation_muted.
7. Run mobile tests for loading, optimistic success, rollback, system-permission copy, accessible switch label, and safe-area layout.
8. Inspect structured logs and Operations Console payloads to prove no message body, sender name, chat title, token, or raw provider response is emitted.

Explicit follow-ups#

After version one has reliable production evidence, add timed mute choices (one hour, until tomorrow, custom date), group-only mentions/replies, and a notification schedule. Those capabilities require an explicit expiry model and a separate product decision; they must not be silently inferred from the basic on/off setting.