Prerequisites
- A Courier API key
- Courier Inbox in your app, signed in as the assignee
- A connected SMS provider
- Your users stored in Courier with a phone number
- An HTTPS endpoint in your app that returns the current on-call’s phone number
Build the Journey
Create the Journey and its trigger
alert-escalation, and choose the API Invoke trigger.Add four fields to the trigger schema:alert_id: your ID for the alertunit_id: the team, unit, or service the alert belongs tounit_name: its display name, likeUnit 4Balert_url: the alert’s page in your app
Send the alert to the assignee's Inbox
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.The run’s user is the assignee, so the message lands in their Inbox.Wait 5 minutes
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.Text the assignee
Wait 5 more minutes
Look up who's on call
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: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.Text the on-call
data.oncall_phone. This text goes to the on-call instead of the assignee.Set a cancelation token and publish
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
Start the escalation when the alert fires
POST /journeys/{templateId}/invoke with the assignee as the user. Replace alert-escalation with your Journey ID.Cancel the run when someone acknowledges
POST /journeys/cancel with the alert’s token. Steps still waiting in a delay never fire, so nobody gets paged for an alert that’s already handled.Verify
Run a fast copy
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.Let it escalate
Acknowledge one
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
Why cancel from my app instead of branching on whether the Inbox message was opened?
Why cancel from my app instead of branching on whether the Inbox message was opened?
Can the escalation page a Slack or Microsoft Teams channel?
Can the escalation page a Slack or Microsoft Teams channel?
Can I add more escalation levels?
Can I add more escalation levels?