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

# On-call escalation

> Page the on-call responder by text message and phone call, and escalate until someone acknowledges.

On-call escalation turns an incident into a page. Squasher texts the person who is on call, calls them if nobody acknowledges, and moves to the next level of responders until someone acknowledges or the incident is resolved.

<Note>
  Squasher does not send texts or calls yet. Until text and voice delivery is turned on, each text
  and call step is recorded as `blocked` on the page timeline, and escalation moves to the next
  step. Use [notifications](/features/alerts) to reach responders today.
</Note>

You configure three things:

* **Escalation policy** — who to page, in which order, and how.
* **Phone numbers** — each responder adds and verifies their own number.
* **Notification route** — an **On-call escalation** destination on a route starts the policy when an incident opens.

## Default behavior

A new level uses this sequence unless you change it:

1. Text the responder with the incident title, severity, a link to the incident, and `Reply 1 to acknowledge.`
2. If nobody acknowledges within 60 seconds, call the responder. The call reads the incident summary and says "Press 1 to acknowledge."
3. If nobody acknowledges within another 60 seconds, call again.
4. If nobody acknowledges within another 60 seconds, go to the next level and use the same sequence.

After the last level, Squasher runs the whole policy again `loop_count` more times (default `1`). If nobody acknowledges after the last loop, the page is marked **exhausted**.

Example with two levels and the default settings:

| Time  | Level         | Action           |
| ----- | ------------- | ---------------- |
| 0:00  | 1 (primary)   | Text             |
| 1:00  | 1 (primary)   | Call             |
| 2:00  | 1 (primary)   | Call             |
| 3:00  | 2 (secondary) | Text             |
| 4:00  | 2 (secondary) | Call             |
| 5:00  | 2 (secondary) | Call             |
| 6:00  | 1 (loop 2)    | Text, call, call |
| 9:00  | 2 (loop 2)    | Text, call, call |
| 12:00 | —             | Page exhausted   |

A text message looks like this:

```text theme={null}
Squasher [SEV-1] API: 500 Error Rate Spike https://app.squasher.ai/acme/api/incidents/inc_42 Reply 1 to acknowledge.
```

Long titles are shortened. A text that the carrier cannot deliver within 10 minutes is dropped, so a responder does not get an old page later.

## Escalation policies

A policy has ordered **levels**. Each level has:

* **Targets** — one or more on-call schedules and/or people. A schedule target pages the person who is on call for that schedule at the time of each step, so a handoff during a page is followed. A person target always pages that person.
* **Steps** — the channels to use, in order. Each step has a channel (`sms` or `voice`), a wait time, and a repeat count.

Squasher pages every target on a level at the same time, on every verified phone number that the responder has.

| Setting                    | Default                   | Limits          |
| -------------------------- | ------------------------- | --------------- |
| Levels per policy          | —                         | 1–10            |
| Targets per level          | —                         | 1–10            |
| Steps per level            | Text, then call two times | 1–10            |
| Wait after each step       | 60 seconds                | 15–3600 seconds |
| Repeat count for a step    | 1                         | 1–5             |
| Loops after the last level | 1                         | 0–9             |

Every wait is set per step. For example, a step `{ "channel": "voice", "wait_seconds": 120, "repeat": 2 }` calls, waits 120 seconds, calls again, and waits 120 seconds before the next step.

A policy is team-wide by default. A project-scoped policy is available only to that project.

A page uses the policy as it was when the page started. If you edit a policy, active pages do not change.

### When a level has nobody to page

If a level has no responder with a verified phone number (for example, nobody is on call for the schedule), Squasher records the level as skipped on the page timeline and goes to the next level immediately.

Squasher also skips a step for a number when:

* The responder turned off that channel for the number.
* The number replied STOP (text steps only).

## Acknowledging a page

A responder can acknowledge a page in these ways:

* Reply `1` or `ACK` to the text message. `acknowledge` also works. Upper or lower case is accepted.
* Press `1` during the call.
* Select **Acknowledge** on the incident in the dashboard.
* Use the [On-call API](/api-reference/on-call#pages).

A text reply acknowledges the most recent active page that was sent to that number. Squasher replies with a confirmation.

When a page is acknowledged, the incident is also acknowledged. The route's other destinations get the `acknowledged` event if they subscribe to it.

These events also stop escalation:

* Somebody acknowledges the incident from anywhere (dashboard, Slack, the API, or another page).
* The incident is resolved.

Acknowledging or resolving the incident stops every active page for that incident.

<Note>
  A voicemail or answering machine does not acknowledge a page. If a machine answers, Squasher
  leaves a short message and escalation continues.
</Note>

## When a page is exhausted

If nobody acknowledges after the last loop:

* The page status changes to `exhausted`. The page stays visible on the incident.
* The incident stays open and unacknowledged.
* Squasher notifies the route's other destinations (for example Slack, email, or a webhook), labeled **On-call page not acknowledged**. The route does not need to subscribe to a separate event for this.

## Phone numbers

Each responder adds their own phone number in **Account settings**:

1. Enter the number in international format, for example `+14155550123`.
2. Select the consent checkbox to agree to receive automated alert texts and calls.
3. Squasher sends a one-time code by text message. Enter the code to verify the number. The code expires after 10 minutes.

Squasher pages only verified numbers. Each number has separate **SMS** and **Voice** switches, so a responder can, for example, receive calls but no texts.

Other people cannot add a number for you. Page timelines show numbers masked, for example `+1•••••0100`.

### Text message keywords

* **STOP** — stops texts to that number. Squasher can still call the number.
* **START** — starts texts to that number again.
* **HELP** — returns help information.

The carrier handles these keywords and sends the confirmation message. Standard message and data rates may apply.

## Set up paging

1. Each responder adds and verifies a phone number in **Account settings**.
2. Create an escalation policy. Add levels with on-call schedules or people as targets. Keep the default steps or change them.
3. Open **Settings → Notifications** and create a destination of type **On-call escalation**. Select the policy.
4. Attach the destination to a route that includes the `opened` event. Use the route's severity conditions if only some incidents should page.
5. Open a test incident to check the complete path. **Send test** is not available for On-call escalation destinations.

Attach Slack or email destinations to the same route. They receive the normal incident events and the exhausted notice.

## Page timeline

Each incident shows its pages and a timeline of every text and call: the level, the loop, the channel, the masked number, and the result. Results include `delivered`, `answered`, `no_answer`, `busy`, `machine` (voicemail), `failed`, `skipped`, and `blocked`.

## Plan availability

Text and voice paging use the SMS alerts and voice alerts included in your plan. Availability depends on your plan. See the [pricing page](https://squasher.ai/pricing) and [Plans and billing](/features/plans-and-billing).

If your plan does not include a channel, or the monthly allowance for that channel is used, the step is recorded as `blocked` on the page timeline and escalation continues with the next step. Use the [usage endpoint](/api-reference/on-call#usage) to see how many texts and calls your organization sent this month.

## Agent handoff

```text theme={null}
Review Squasher on-call escalation for project <project_id>. Start read-only: list escalation policies, check who is on call now, and list recent pages with their timelines. Tell me which levels have nobody with a verified phone number. Propose the smallest change, and do not create, change, or delete a policy, a destination, or a route until I confirm.
```

## Related guides

* [On-call](/features/on-call)
* [Notifications](/features/alerts)
* [On-call API](/api-reference/on-call)
* [Notifications API](/api-reference/alerts)