In-app inbox & real-time updates

Every notification delivered through the in_app channel becomes an item in the recipient’s inbox. This guide shows how to display that inbox, mark items as read, and stream new notifications to your UI in real time. The inbox lives in the archie_notifications_in_app table, exposed through the auto-generated GraphQL operations on your project endpoint (https://archie-core.services.archie.com/graphql) with the usual X-Project-Id, X-Environment, and Authorization headers.

What an inbox item contains

Field	Meaning
`receiverId`	The user the item belongs to.
`notificationType`	The type it was sent from (its `eventKey`, `name`, …).
`notificationKey`	The event key, stored on the item for convenience.
`params`	The variables used to render it (your JSON payload).
`actionUrl` / `actionText`	Optional call-to-action link and label.
`isRead` / `readAt`	Read state and timestamp.
`metadata`	Optional extra JSON you attached.
`expiresAt`	When the item expires and should stop being shown.
`createdAt`	When it arrived.

Show a user’s inbox

Fetch the most recent, non-expired items for the signed-in user:

query Inbox {
  archieNotificationsInApp(
    filter: { receiverId: { equals: "2685ec12-a4c7-491d-a155-d0b09190993b" } }
    orderBy: { createdAt: DESC }
    first: 20
  ) {
    items {
      id
      notificationKey
      params
      actionUrl
      actionText
      isRead
      createdAt
      notificationType {
        name
      }
    }
  }
}

Soft-deleted records. List queries exclude soft-deleted rows by default, so a dismissed or removed inbox item won’t reappear. To include records that have been soft-deleted, pass the withDeleted: true argument on the list query (e.g., archieNotificationsInApp(withDeleted: true) { items { id } }). Omit it — or set it to false — to return only active rows.

Count unread

Use a filter to show an unread badge:

query UnreadCount {
  archieNotificationsInApp(
    filter: {
      receiverId: { equals: "2685ec12-…" }
      isRead: { equals: false }
    }
  ) {
    count
  }
}

Mark as read

mutation MarkRead {
  updateArchieNotificationsInApp(
    id: "item-id…"
    input: { isRead: true, readAt: "2026-06-24T15:00:00Z" }
  ) {
    id
    isRead
    readAt
  }
}

Receive notifications in real time

To make new notifications appear instantly — without polling — use Archie’s subscriptions. There are two steps: register a subscription configuration, then connect over a WebSocket to receive events.

1. Register the subscription

Use the system { createSubscription } mutation to declare which table and operations to watch. For an inbox, watch the in-app table for new rows (CREATE):

mutation CreateInboxSubscription($input: SubscriptionInput!) {
  system {
    createSubscription(input: $input) {
      id
      active
      name
    }
  }
}

Variables

{
  "input": {
    "name": "in_app_inbox",
    "description": "New in-app notifications",
    "active": true,
    "tables": [
      {
        "table": "archie_notifications_in_app",
        "operations": ["CREATE"],
        "fields": ["id", "receiver_id", "notification_key", "params", "action_url", "action_text", "is_read", "created_at"]
      }
    ]
  }
}

Inside a subscription’s fields list, use the raw column names in snake_case (e.g., receiver_id, notification_key, is_read) — these are the database column names, not the camelCase API fields.

2. Connect and listen

Open a WebSocket to the project’s subscription endpoint and you’ll receive an event each time a matching row is created:

wss://archie-core.archie-platform.com/subscriptions?project_id=<your-project-id>

When a new notification is delivered to a user, your client receives the row described by the fields you registered. Filter client-side by receiver_id so each user only reacts to their own items, then update the inbox UI (prepend the item, bump the unread badge).

Watch ["CREATE", "UPDATE"] if you also want live updates when an item is marked as read on another device.

Putting it together

A complete in-app experience usually looks like this:

On load, query the inbox and the unread count.
Register (once) the in_app_inbox subscription and connect the WebSocket.
When an event arrives, prepend the new item and increment the badge.
When the user opens an item, mark it read and decrement the badge.

For email and other channels, no inbox handling is needed — Archie delivers those directly through the configured integration.

Home

Blueprint

Design

Frontend

Backend

Assets

What an inbox item contains

Show a user’s inbox

Count unread

Mark as read

Receive notifications in real time

1. Register the subscription

2. Connect and listen

Putting it together

​What an inbox item contains

​Show a user’s inbox

​Count unread

​Mark as read

​Receive notifications in real time

​1. Register the subscription

​2. Connect and listen

​Putting it together

What an inbox item contains

Show a user’s inbox

Count unread

Mark as read

Receive notifications in real time

1. Register the subscription

2. Connect and listen

Putting it together