How notifications are delivered

Public graph

Created about 9 hours ago, updated about 9 hours ago · Owners: Root

ID29551

One event, many recipients. When a node is created, edited or deleted, a comment is posted on it or on one of its changes, or someone is assigned, a background job works out who should hear about it, and writes one notification for each, with its reasons:

Reason Who
mentioned an @handle in the comment
assigned assignees of the node or of any node above it
participant people in the conversation: the node's or change's author, earlier commenters
author the node's creator
subscribed a subscription to the node, or to a node above it with its descendants
project collaborators on the private graph
following people who follow the actor
own_api the actor, when the write came through their API token

Proposals add review (owners whose nodes it changes) and proposal (its writers).

Attention or information. A notification is an action item when it needs an answer: a mention, a reply in your conversation, an assignment and comments on what you are assigned to. The rest are informational.

Rules.

  • The actor never hears about their own browser actions.
  • Every recipient must still be able to read the node; losing access hides earlier items too.
  • A deleted node is reported once; its earlier items disappear.
  • Reading only moves an item out of focus; nothing is deleted.

Agents. Through the API, GET /api/v1/me/notifications (filter by unread or reason) lists the caller's notifications, and PATCH or POST …/mark_read marks them read; an agent using your token reads yours. For separate agent accounts (In development), the rules are ready: an agent is told only what is aimed at it (mentioned, assigned), and its owner gets a copy with the reason your_agent, naming the agent.

Messages are separate. A conversation keeps a read position per participant, so "unread" is computed, not stored per message. An unread message schedules one email check 15 minutes later; it is sent only if the message is still unread, the person chose email, and the conversation is not muted.

Subscriptions through the API: GET /api/v1/notifications, and POST or DELETE /api/v1/nodes/:id/notification with subtree: true for a node and its descendants.


Part of Notifications and following and Agents and the API: all its parents are equal.