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

> ## Agent Instructions
> Install the Courier skill before writing code: `npx skills add trycourier/courier-skills`. It carries the verified SDK shapes and the rules you cannot get wrong.
> Authenticate every request with `Authorization: Bearer <API_KEY>`. A workspace has several environments and each has its own keys, which are plain `pk_` strings with no environment prefix. Start with Test.
> Send with `client.send.message` from the Node SDK (`@trycourier/courier` v7 and later, where the client is the default import). Reference a template by its `nt_` id or its alias.
> A send accepts a bare Elemental element list, but storing content on a template requires the top-level elements wrapped in a channel element.
> To translate a template, write one locale at a time with `PUT /notifications/{id}/locales/{localeId}`, which merges into the existing translations. `PUT /notifications/{id}/content` and `PUT /notifications/{id}/elements/{elementId}` overwrite translations along with the content, so send each element's `id` and `locales` back, and first remove every `checksum` and any `locales` key that starts with an underscore.
> Templates and journeys can be built in the Courier app or created through the API. Either way they live in the workspace and are referenced by ID when you send.
> The hosted MCP server is https://mcp.courier.com. For a briefing on what Courier is and when to use it, read https://www.courier.com/llms.txt.
> Prefer the Guides tab for how-do-I questions and the Docs tab for how-does-it-behave questions. The API reference lives under /api-reference.

# Escalate an alert until someone acknowledges it

> Build an alert escalation policy in one Journey: Inbox first, SMS after 5 minutes, then the on-call. Your app cancels it when someone acknowledges.

Send an alert to the assignee's Inbox, text them if it sits for 5 minutes, and text the on-call 5 minutes later. That's an escalation policy built as one Journey, and your app stops it with one API call when someone takes the alert.

It escalates alerts your product sends to its own users, such as clinicians, field technicians, or account owners. Each message names where the alert is and links to your app, so the details stay behind sign-in. For healthcare alerts, that keeps PHI out of the message. See [HIPAA and BAAs](https://www.courier.com/docs/security/hipaa.md).

## Prerequisites

* [A Courier API key](https://app.courier.com/settings/api-keys)
* [Courier Inbox in your app](https://www.courier.com/docs/in-app/overview.md), signed in as the assignee
* [A connected SMS provider](https://www.courier.com/docs/integrations/sms/overview.md)
* [Your users stored in Courier](https://www.courier.com/docs/guides/import-your-users.md) with a phone number
* An HTTPS endpoint in your app that returns the current on-call's phone number

## Build the Journey

**1. Create the Journey and its trigger**

Open [Journeys](https://app.courier.com/orchestration/journeys), select **New Journey**, name it `alert-escalation`, and choose the **API Invoke** trigger.

Add four fields to the trigger schema:

* `alert_id`: your ID for the alert
* `unit_id`: the team, unit, or service the alert belongs to
* `unit_name`: its display name, like `Unit 4B`
* `alert_url`: the alert's page in your app

**2. Send the alert to the assignee's Inbox**

Add a **send** node on the **In-app / Inbox** channel and select **+ Create** to write the template. Name the location and nothing about the patient or the finding:

```text theme={null}
New alert for {{unit_name}}. Open the app to review.
```

Below the text, add a **Button** block labeled `Review alert` with its link set to `{{alert_url}}`. The Inbox shows it as an action on the message, so the assignee goes straight to the alert. See [Button](https://www.courier.com/docs/design/templates/blocks.md#button).

The run's user is the assignee, so the message lands in their Inbox.

**3. Wait 5 minutes**

Add a **delay** node set to **Duration**, 5 minutes.

To set the wait per alert, such as shorter for critical ones, add an `escalate_after` field to the trigger schema. Turn on **Dynamic Interval**, select `data.escalate_after`, and send an ISO 8601 duration like `PT2M` in that field. See [Delay node](https://www.courier.com/docs/journeys/nodes/delay.md#dynamic-interval).

**4. Text the assignee**

Add an **SMS** send node with the link in the text, since SMS has no buttons:

```text theme={null}
New alert for {{unit_name}}. Review it: {{alert_url}}
```

It goes to the phone number on the assignee's profile.

**5. Wait 5 more minutes**

Add a second **delay** of 5 minutes.

**6. Look up who's on call**

Add a **fetch data** node and select **Setup Request**. Set the method to **GET** and the URL to your on-call endpoint, such as `https://api.example.com/oncall/{{data.unit_id}}`, and add your API's auth header. Keep the merge strategy at **Soft Merge**.

The endpoint returns the on-call's number, which Courier merges into the run's data:

```json theme={null}
{ "oncall_phone": "+15551234567" }
```

Select **Execute Step** with a test `unit_id` so `oncall_phone` appears in the field list.

**A fetch that fails ends the run before the on-call text.** Send `unit_id` on every invoke, because a URL variable with no value fails the fetch. Have the endpoint always return a number, such as a charge nurse or a team lead when nobody's scheduled. See [When a fetch fails](https://www.courier.com/docs/journeys/nodes/fetch-data.md#when-a-fetch-fails).

**7. Text the on-call**

Add another **SMS** send node with the same text as the assignee's. Next to **Recipient Override**, select **Add** and choose `data.oncall_phone`. This text goes to the on-call instead of the assignee.

**8. Set a cancelation token and publish**

In the Journey's settings, set the **cancelation token** to `alert-{{data.alert_id}}`. Each alert's run carries its own token, so acknowledging one alert stops only that alert's escalation. Always pass `alert_id`, because a token that references missing data isn't set.

Publish the three templates, then select **Publish** on the Journey and copy its ID.

## Trigger it from your app

**1. Start the escalation when the alert fires**

Call [`POST /journeys/{templateId}/invoke`](https://www.courier.com/docs/api-reference/journeys/invoke-a-journey) with the assignee as the user. Replace `alert-escalation` with your Journey ID.

```javascript Node.js theme={null}
const journeysInvokeResponse = await client.journeys.invoke('alert-escalation', {
  user_id: 'user_123',
  data: {
    alert_id: 'alrt_7Kd2',
    unit_id: 'unit_4b',
    unit_name: 'Unit 4B',
    alert_url: 'https://app.example.com/alerts/alrt_7Kd2',
  },
  'Idempotency-Key': 'alert-fired-alrt_7Kd2-2026-11-19T14:05:00Z',
});
```

```python Python theme={null}
journeys_invoke_response = client.journeys.invoke(
    template_id="alert-escalation",
    user_id="user_123",
    data={
        "alert_id": "alrt_7Kd2",
        "unit_id": "unit_4b",
        "unit_name": "Unit 4B",
        "alert_url": "https://app.example.com/alerts/alrt_7Kd2",
    },
    idempotency_key="alert-fired-alrt_7Kd2-2026-11-19T14:05:00Z",
)
```

```bash cURL theme={null}
curl -X POST https://api.courier.com/journeys/alert-escalation/invoke \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: alert-fired-alrt_7Kd2-2026-11-19T14:05:00Z" \
  -d "{
    \"user_id\": \"user_123\",
    \"data\": {
      \"alert_id\": \"alrt_7Kd2\",
      \"unit_id\": \"unit_4b\",
      \"unit_name\": \"Unit 4B\",
      \"alert_url\": \"https://app.example.com/alerts/alrt_7Kd2\"
    }
  }"
```

```ruby Ruby theme={null}
journeys_invoke_response = courier.journeys.invoke(
  "alert-escalation",
  user_id: "user_123",
  data: {
    alert_id: "alrt_7Kd2",
    unit_id: "unit_4b",
    unit_name: "Unit 4B",
    alert_url: "https://app.example.com/alerts/alrt_7Kd2",
  },
  idempotency_key: "alert-fired-alrt_7Kd2-2026-11-19T14:05:00Z"
)
```

```go Go theme={null}
journeysInvokeResponse, err := client.Journeys.Invoke(
	context.TODO(),
	"alert-escalation",
	courier.JourneyInvokeParams{
		JourneysInvokeRequest: courier.JourneysInvokeRequestParam{
			UserID: courier.String("user_123"),
			Data: map[string]any{
				"alert_id":  "alrt_7Kd2",
				"unit_id":   "unit_4b",
				"unit_name": "Unit 4B",
				"alert_url": "https://app.example.com/alerts/alrt_7Kd2",
			},
		},
		IdempotencyKey: courier.String("alert-fired-alrt_7Kd2-2026-11-19T14:05:00Z"),
	},
)
```

```java Java theme={null}
JourneyInvokeParams params = JourneyInvokeParams.builder()
    .templateId("alert-escalation")
    .journeysInvokeRequest(JourneysInvokeRequest.builder()
        .userId("user_123")
        .data(JourneysInvokeRequest.Data.builder()
            .putAdditionalProperty("alert_id", JsonValue.from("alrt_7Kd2"))
            .putAdditionalProperty("unit_id", JsonValue.from("unit_4b"))
            .putAdditionalProperty("unit_name", JsonValue.from("Unit 4B"))
            .putAdditionalProperty("alert_url", JsonValue.from("https://app.example.com/alerts/alrt_7Kd2"))
            .build())
        .build())
    .idempotencyKey("alert-fired-alrt_7Kd2-2026-11-19T14:05:00Z")
    .build();
JourneysInvokeResponse journeysInvokeResponse = client.journeys().invoke(params);
```

```php PHP theme={null}
$journeysInvokeResponse = $client->journeys->invoke(
  'alert-escalation',
  userID: 'user_123',
  data: [
    'alert_id' => 'alrt_7Kd2',
    'unit_id' => 'unit_4b',
    'unit_name' => 'Unit 4B',
    'alert_url' => 'https://app.example.com/alerts/alrt_7Kd2',
  ],
  idempotencyKey: 'alert-fired-alrt_7Kd2-2026-11-19T14:05:00Z',
);
```

```csharp C# theme={null}
JourneyInvokeParams parameters = new()
{
    TemplateID = "alert-escalation",
    UserID = "user_123",
    Data = new Dictionary<string, JsonElement>()
    {
        { "alert_id", JsonSerializer.SerializeToElement("alrt_7Kd2") },
        { "unit_id", JsonSerializer.SerializeToElement("unit_4b") },
        { "unit_name", JsonSerializer.SerializeToElement("Unit 4B") },
        { "alert_url", JsonSerializer.SerializeToElement("https://app.example.com/alerts/alrt_7Kd2") },
    },
    IdempotencyKey = "alert-fired-alrt_7Kd2-2026-11-19T14:05:00Z",
};

var journeysInvokeResponse = await client.Journeys.Invoke(parameters);
```

```bash CLI theme={null}
courier journeys invoke \
  --api-key "$COURIER_API_KEY" \
  --template-id alert-escalation \
  --user-id user_123 \
  --idempotency-key alert-fired-alrt_7Kd2-2026-11-19T14:05:00Z \
  --data "{\"alert_id\":\"alrt_7Kd2\",\"unit_id\":\"unit_4b\",\"unit_name\":\"Unit 4B\",\"alert_url\":\"https://app.example.com/alerts/alrt_7Kd2\"}"
```

```text MCP theme={null}
With Courier MCP, start the alert-escalation journey for user_123 with alert_id alrt_7Kd2, unit_id unit_4b, unit_name Unit 4B, and alert_url https://app.example.com/alerts/alrt_7Kd2.
```

Build the idempotency key from the alert's ID and the time it fired. A retried request returns the same run, so one firing never starts two escalations. An alert that fires again later gets a new key and a new escalation, instead of the earlier, canceled run.

**2. Cancel the run when someone acknowledges**

In the code that records the acknowledgment, call [`POST /journeys/cancel`](https://www.courier.com/docs/api-reference/journeys/cancel-journey-runs) with the alert's token. Steps still waiting in a delay never fire, so nobody gets paged for an alert that's already handled.

```javascript Node.js theme={null}
const cancelJourneyResponse = await client.journeys.cancel({ cancelation_token: 'alert-alrt_7Kd2' });
```

```python Python theme={null}
cancel_journey_response = client.journeys.cancel(
    cancelation_token="alert-alrt_7Kd2",
)
```

```bash cURL theme={null}
curl -X POST https://api.courier.com/journeys/cancel \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cancelation_token": "alert-alrt_7Kd2"
  }'
```

```ruby Ruby theme={null}
cancel_journey_response = courier.journeys.cancel(cancel_journey_request: {cancelation_token: "alert-alrt_7Kd2"})
```

```go Go theme={null}
cancelJourneyResponse, err := client.Journeys.Cancel(context.TODO(), courier.JourneyCancelParams{
	CancelJourneyRequest: courier.CancelJourneyRequestUnionParam{
		OfByCancelationToken: &courier.CancelJourneyRequestByCancelationTokenParam{
			CancelationToken: "alert-alrt_7Kd2",
		},
	},
})
```

```java Java theme={null}
CancelJourneyRequest.ByCancelationToken params = CancelJourneyRequest.ByCancelationToken.builder()
    .cancelationToken("alert-alrt_7Kd2")
    .build();
CancelJourneyResponse cancelJourneyResponse = client.journeys().cancel(params);
```

```php PHP theme={null}
$cancelJourneyResponse = $client->journeys->cancel(
  cancelationToken: 'alert-alrt_7Kd2'
);
```

```csharp C# theme={null}
JourneyCancelParams parameters = new()
{
    CancelJourneyRequest = new ByCancelationToken("alert-alrt_7Kd2")
};

var cancelJourneyResponse = await client.Journeys.Cancel(parameters);
```

```bash CLI theme={null}
courier journeys cancel \
  --api-key "$COURIER_API_KEY" \
  --cancelation-token alert-alrt_7Kd2
```

```text MCP theme={null}
With Courier MCP, cancel the journey runs with the cancelation token alert-alrt_7Kd2.
```

Canceling a run that already finished changes nothing, so you can call it on every acknowledgment without checking first.

## Verify

**1. Run a fast copy**

Duplicate the Journey for testing, set both delays to 1 minute, and change its cancelation token to `alert-test-{{data.alert_id}}`. Publish the copy.

**Point the on-call lookup at yourself.** Have your endpoint return your own number for a test unit, such as `unit_test`, and invoke the copy with that `unit_id`. With a real unit, the test texts whoever is on call.

Invoke the copy for a test user whose profile has your phone number.

**2. Let it escalate**

Leave the alert alone. The Inbox message arrives right away, the first text a minute later, and the on-call text a minute after that. Open the Journey's **Logs** tab and select the run to see each step and the fetch response.

**3. Acknowledge one**

Invoke the copy again with a new `alert_id`, and run the cancel call with its test token right away, inside the first minute. No text goes out, and the run reads **Canceled** in the **Logs** tab.

## FAQ

> [accordion] Why cancel from my app instead of branching on whether the Inbox message was opened?
>
> An Inbox open means the assignee opened the message, which doesn't mean they took the alert. Taking the alert happens in your app, so the cancel call belongs in the code that records it.

> [accordion] Can the escalation page a Slack or Microsoft Teams channel?
>
> A Slack or Teams send node can post to your on-call channel as another step, or in place of the on-call text. Set its destination as described in [Slack recipients](https://www.courier.com/docs/journeys/nodes/send.md#slack-recipients) and [Microsoft Teams recipients](https://www.courier.com/docs/journeys/nodes/send.md#microsoft-teams-recipients).

> [accordion] Can I add more escalation levels?
>
> Each level is another delay, fetch, and send node at the end of the chain. The cancelation token covers every step, so one cancel call stops the whole escalation.
