> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bedrock.orinlabs.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Notifications

> How the notification system drives agent attention and scheduling

# Notifications

**Notifications** are the primary mechanism for directing an agent's attention. They replace scattered read-tracking across channels and give you a single, unified queue that determines what the agent works on next.

## How Notifications Work

Every notification has a **priority** that controls agent behavior:

| Priority | Wake Agent | Block Sleep | Use Case                                                |
| -------- | ---------- | ----------- | ------------------------------------------------------- |
| `high`   | Yes        | Yes         | Inbound messages, urgent events, tasks requiring action |
| `low`    | No         | No          | Informational updates, logging, non-urgent reminders    |

* **High-priority** notifications wake the agent immediately and prevent it from sleeping until cleared.
* **Low-priority** notifications are informational — the agent sees them on its next run but isn't woken for them.

The agent must explicitly **clear** each notification to dismiss it.

## Notification Fields

| Field           | Type                | Description                                                                                                                                                                                                                                                                                                        |
| --------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`            | UUID                | Auto-generated unique identifier                                                                                                                                                                                                                                                                                   |
| `agent`         | UUID                | The agent this notification belongs to                                                                                                                                                                                                                                                                             |
| `source`        | string              | Origin of the notification (see [Sources](#sources))                                                                                                                                                                                                                                                               |
| `source_id`     | string              | Context id for the notification. For inbound messaging (`sms`, `mms`, `webchat`, `surge`, etc.) this is the **Contact UUID** the agent should pass to `send_message`, `send_sms`, and attachment tools. The notification `body` may also include a local **Message ID** for `open_sms_attachment` / similar tools. |
| `title`         | string              | Notification title shown to the agent                                                                                                                                                                                                                                                                              |
| `body`          | string              | Additional details/context                                                                                                                                                                                                                                                                                         |
| `priority`      | `"high"` \| `"low"` | Controls wake and sleep behavior                                                                                                                                                                                                                                                                                   |
| `created_at`    | datetime            | When the notification was created                                                                                                                                                                                                                                                                                  |
| `scheduled_for` | datetime \| null    | When the notification becomes active (for future reminders)                                                                                                                                                                                                                                                        |
| `cleared`       | boolean             | Whether the agent has dismissed it                                                                                                                                                                                                                                                                                 |
| `cleared_at`    | datetime \| null    | When it was cleared                                                                                                                                                                                                                                                                                                |

## Agent Tools

The Notifications adapter provides three tools that agents can call directly:

### `list_notifications`

Lists active notifications for the agent. By default only shows uncleared notifications that are not scheduled for the future.

| Parameter         | Type    | Default | Description                                 |
| ----------------- | ------- | ------- | ------------------------------------------- |
| `include_cleared` | boolean | `false` | Include already-cleared notifications       |
| `limit`           | integer | `50`    | Max notifications to return (capped at 100) |

### `clear_notification`

Clears (dismisses) a notification by ID. The agent must clear high-priority notifications before it can sleep.

| Parameter         | Type | Required | Description                     |
| ----------------- | ---- | -------- | ------------------------------- |
| `notification_id` | UUID | Yes      | ID of the notification to clear |

### `create_notification`

Creates a new notification, typically used by the agent to set reminders for itself.

| Parameter       | Type                | Required | Description                                |
| --------------- | ------------------- | -------- | ------------------------------------------ |
| `title`         | string              | Yes      | Notification title                         |
| `body`          | string              | No       | Additional details                         |
| `priority`      | `"high"` \| `"low"` | No       | Defaults to `"low"`                        |
| `scheduled_for` | ISO 8601 datetime   | No       | When the notification should become active |

<Note>
  When an agent creates a notification with `scheduled_for` set to a future time, it won't appear in `list_notifications` until that time arrives. This is how agents create reminders — the notification surfaces when the schedule time passes and the agent is next awake.
</Note>

## Scheduled Notifications (Reminders)

Notifications with `scheduled_for` set to a future datetime act as **reminders**:

1. The notification is created but hidden from `list_notifications`
2. A periodic workflow scans for agents with uncleared high-priority notifications whose `scheduled_for` has passed
3. The agent is woken up and sees the notification

This lets agents (or external systems) schedule future work without needing a separate task model.

```bash theme={null}
curl -X POST https://api.bedrock.orinlabs.org/api/defaults/notifications/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "AGENT_ID",
    "title": "Follow up with customer",
    "body": "Check if they resolved their billing issue",
    "priority": "high",
    "scheduled_for": "2025-01-15T14:00:00Z"
  }'
```

## Sources

The `source` field identifies where a notification came from:

| Source     | Description                                              |
| ---------- | -------------------------------------------------------- |
| `email`    | Inbound email received via AgentMail                     |
| `sms`      | Inbound SMS via Twilio                                   |
| `mms`      | Inbound iMessage/RCS via Linq                            |
| `surge`    | Inbound SMS via Surge                                    |
| `blooio`   | Inbound SMS via Blooio                                   |
| `system`   | System events (OAuth connected, agent created, etc.)     |
| `agent`    | Self-created by the agent (reminders)                    |
| `subagent` | Message from a parent or child agent                     |
| `browser`  | Browser automation task completed, failed, or needs help |
| `api`      | Created via the REST API                                 |
| `portal`   | Created from the Bedrock portal UI                       |

### `source_id` on inbound messages

`list_notifications` labels `source_id` as `contact_id` for human-facing messaging sources. Inbound webhooks store the **sender's Contact UUID** in `source_id` (not the Twilio MessageSid, Surge message id, or other provider id). That value is the same id `send_message` / `send_sms` / `open_sms_attachment` expect.

When a message includes attachments, the notification `body` also carries the local message row's UUID and the correct `open_*_attachment` tool name, for example:

```text theme={null}
[1 attachment(s) included - Message ID: <uuid>; use open_sms_attachment(message_id="<uuid>") to view]
```

Do not pass provider message ids or the notification's own `Notification ID` as `contact_id`.

## Wake/Sleep Lifecycle

Notifications integrate directly with the agent's autonomous runtime:

1. **Inbound event** (e.g. SMS received) → `create_notification(priority="high")`
2. High-priority notification triggers `wake_agent` → agent starts running
3. Agent calls `list_notifications` to see what needs attention
4. Agent processes the notification (reads the SMS, responds, etc.)
5. Agent calls `clear_notification` to dismiss it
6. Agent attempts to `sleep` — succeeds because no uncleared high-priority notifications remain

If an agent tries to sleep with uncleared high-priority notifications, the sleep tool returns an error instructing it to clear them first.

## REST API

Manage notifications externally via the REST API. All endpoints require authentication (API key or portal token).

**Base path:** `/api/defaults/notifications/`

### List Notifications

```bash theme={null}
curl -X GET "https://api.bedrock.orinlabs.org/api/defaults/notifications/?agent=AGENT_ID&cleared=false&priority=high" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

| Query Parameter | Description                                 |
| --------------- | ------------------------------------------- |
| `agent`         | Filter by agent UUID                        |
| `cleared`       | Filter by cleared status (`true` / `false`) |
| `priority`      | Filter by priority (`high` / `low`)         |

### Create a Notification

```bash theme={null}
curl -X POST https://api.bedrock.orinlabs.org/api/defaults/notifications/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "AGENT_ID",
    "title": "New support ticket #1234",
    "body": "Customer reports login issue",
    "source": "api",
    "priority": "high"
  }'
```

Creating a notification with `priority: "high"` (and no `scheduled_for`) will **immediately wake the agent**.

### Update a Notification

```bash theme={null}
curl -X PATCH https://api.bedrock.orinlabs.org/api/defaults/notifications/NOTIFICATION_ID/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cleared": true}'
```

### Delete a Notification

```bash theme={null}
curl -X DELETE https://api.bedrock.orinlabs.org/api/defaults/notifications/NOTIFICATION_ID/ \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response Format

```json theme={null}
{
  "id": "notification-uuid",
  "agent": "agent-uuid",
  "source": "api",
  "source_id": "",
  "title": "New support ticket #1234",
  "body": "Customer reports login issue",
  "priority": "high",
  "created_at": "2025-01-15T10:30:00Z",
  "scheduled_for": null,
  "cleared": false,
  "cleared_at": null
}
```

## Common Patterns

### Triggering Agent Work from Your Backend

Use the API to create a high-priority notification whenever your system has work for an agent:

```python theme={null}
import requests

def assign_task_to_agent(agent_id: str, task_title: str, task_details: str):
    requests.post(
        "https://api.bedrock.orinlabs.org/api/defaults/notifications/",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        json={
            "agent": agent_id,
            "title": task_title,
            "body": task_details,
            "source": "api",
            "priority": "high",
        },
    )
```

The agent wakes up, reads the notification, and acts on it autonomously.

### Polling for Completed Work

Check for cleared notifications to know when an agent has handled something:

```bash theme={null}
curl -X GET "https://api.bedrock.orinlabs.org/api/defaults/notifications/?agent=AGENT_ID&cleared=true&source=api" \
  -H "Authorization: Bearer YOUR_API_KEY"
```