# Page a responder

For existing workplace teams, choose the current responder and escalate unanswered pages. This chapter covers rotations, page creation, and the human acknowledgement that stops escalation.

HTML: https://notify.belweave.ai/docs/oncall

## Schedule responders

An existing workplace team’s owner or admin can define a responder order. Daily/weekly handoffs use an IANA time zone and local clock, preserving the chosen local time through daylight-saving changes.

```bash
notify oncall create --team team_... --name Primary \
  --members user_a,user_b,user_c --period weekly \
  --handoff 09:00 --timezone America/New_York
```

If `startsAt` is absent, the first responder’s shift begins at the most recent handoff. A timed override replaces the rotation during its window; members can schedule their own coverage. Group reads include current and upcoming shifts.

## Escalation and deduplication

A new page contacts the current responder, or the entire group if no responder is scheduled. Configured escalation continues until an acknowledgement stops it:

| Field | Type | Description |
| --- | --- | --- |
| `afterMinutes` | integer | Minutes after the previous step (or the page) without an acknowledgement. |
| `target` | next \| group | `next` pages the next person in the rotation; `group` pages everyone in it who has not been paged yet. |

The default schedule contacts the next responder after five minutes, then the group ten minutes later. Repeated `dedupKey` values join an existing open page and increment `repeatCount` without issuing another initial page.

```bash
notify page ocg_example_maintenance "Cold-room temperature above threshold" \
  --body "Sensor reports 12°C since 14:02" --dedup-key cold-room-temperature
```

## Page from a service

A service can route a message to a rotation using `oncall`. Its owner must belong to that workplace team. Do not combine it with `deviceIds`, `group`, or `response`. The webhook `Idempotency-Key` becomes the page deduplication key.

```json
{
  "title": "Cold-room monitor",
  "body": "Temperature above threshold for 5 minutes",
  "oncall": "ocg_example_maintenance"
}
```

The page response includes `pageId` and provider-acceptance count `delivered`. Keep the body within 2,000 characters. CLI equivalents are `notify page` and `notify send --oncall`.

## Acknowledge, escalate, and resolve

A current teammate can acknowledge through a supported Lock Screen action, the app, or the website. The first accepted acknowledgement stops escalation; later acknowledgements are refused. Notify requests clearing the other devices’ alerts. Escalate immediately advances to the next step.

> Acknowledgement and escalation require a person. Agents can raise, inspect, and resolve pages, but cannot acknowledge or escalate as if a person had taken responsibility.

When the incident is finished, resolve it on the website or with `notify pages resolve page_... --note "Maintenance completed"`. Resolution also stops escalation on a page that was never acknowledged.