Configure direct paging for Grafana IRM

While Grafana IRM primarily uses automated workflows for alert escalation and incident response, you sometimes need to manually alert specific teams or individuals. Direct paging allows you to quickly create alert groups to notify teams or users outside of your pre-configured automation.

Grafana IRM automatically creates direct paging integrations for each team. These integrations allow teams to page each other directly through the UI, messaging apps, or API. Direct paging can:

Route alerts to the team’s chat channels
Trigger the team’s escalation chain
Support different notification paths for regular and important alerts

Before you begin

Teams must configure their direct paging integrations with escalation chains and notification channels to be contactable.

To manually control direct paging integrations:

Navigate to IRM > Settings > Admin & API
Enable Manually manage direct paging integrations
Choose how to manage your direct paging integrations:
- Web UI Management: Create, edit, and delete direct paging integrations through the Integrations page
- Infrastructure as Code (IaC): Manage through Terraform or other IaC tools by either:
  - Importing existing integrations into your IaC tooling
  - Deleting and recreating them through IaC

When the Manually manage direct paging integrations setting is enabled, you’ll see Direct Paging as an Integration type when creating new integrations via the web.

For more detail, refer to Manually manage direct paging.

Configure direct paging for a team

When not manually managed, direct paging integrations come pre-configured with two routes:

A priority route for important escalations
A default route for standard alerts

To configure a team’s direct paging integration, add the appropriate escalation chains and notification channels:

Navigate to IRM > Integrations > Monitoring Systems
Locate the team’s Direct paging integration
Configure:
- Assign escalation chains to the pre-configured routes
- Set up chat channel notifications
- Customize other settings as needed
Test the configuration by creating a test alert group

Important escalations

The default payload of alerts generated by Direct Paging integrations includes an oncall.important boolean field.

You can set the value of this field when using Direct Paging via the Escalation API or when paging a user or team directly in the UI - either from the Alert Groups page, or within an Incident.

The important field helps the person sending the page convey urgency:

Important: “This is urgent - I may need to wake someone up.”
Default: “This is informative, or it can wait a few hours.”

Teams can configure their Direct Paging integration routes to handle incoming pages differently based on this field. This allows for tailored routing behavior depending on the urgency as perceived by the person initiating the page.

As described in Configure Direct Paging for a team, if you’re using the default setup (not manually managing the Direct Paging integrations), each team’s Direct Paging integration includes two pre-configured routes:

Priority route: Matches pages marked as important using the template {{ payload.oncall.important }}
Default route: Catches all other, non-important pages

Page a team

Teams must have an escalation chain or at least one messaging app connected to be paged.

To page a team:

Navigate to the Alert groups page
Click + Escalation
Configure the alert group:
- Message: Add details and context for the team
- Team: Select the team to page (only teams with configured direct paging integrations appear)
- Users: (Optional) Add specific users and specify if they should be notified via Default or Important notifications

Tip
You can also page teams using the /grafana escalate command in Slack.

Add responders to an alert group

You can add more responders to an existing alert group in two ways:

In the UI: Click + Add in the “Participants” section of the alert group
In Slack: Use the Responders button in the alert group message

Adding responders:

Immediately notifies the new participants
Works even if the alert group is silenced or acknowledged
Does not affect the existing escalation chain
Cannot be used to page entire teams (create a new alert group instead)

Alert payload

The following payload is an example of an alert generated from a Direct Paging integration:

{
  "oncall": {
    "title": "IRM is paging Network team to join escalation",
    "message": "I really need someone from your team to come take a look! The k8s cluster is down!",
    "uid": "8a20b8d1-56fd-482e-824e-43fbd1bd7b10",
    "author_username": "irm",
    "permalink": null,
    "important": true
  },
  "incident": {
    "id": "3",
    "title": "Kubernetes Cluster Outage",
    "labels": {
      "service_name": "payments_service",
      "region": "us-east-1"
    },
    "status": "active",
    "summary": "something is on fire!",
    "severity": "Critical",
    "declared_at": "2025-05-29T20:43:24.539889Z"
  },
  "metadata": {
    "service": "payments_service",
    "zoom_meeting_link": "https://zoom.us/j/123456789?pwd=abc123xyz"
  }
}

Things to note

incident: The incident object is only populated if the Direct Page originated from an incident. Refer to Add and manage incident participants to learn more.
metadata: The metadata object provides a structured way to include additional context when Direct Paging a user or team. This object is only populated when Direct Paging via the OnCall public API. Refer to the Escalation API documentation to learn more.