---
title: "Customize alert templates in Grafana IRM | Grafana Cloud documentation"
description: "Customize Jinja2 alert templates to control how Grafana IRM formats, groups, resolves, and acknowledges alerts."
---

# Customize alert templates in Grafana IRM

Alert templates in Grafana IRM control how alert information is formatted, processed, and displayed to users. Using Jinja2 templates, you can customize how alerts appear in different notification channels and control alert behavior such as grouping and auto-resolution.

## About alert templates

Grafana IRM integrates with your monitoring systems through webhooks that deliver JSON payloads. These raw payloads often contain complex data structures that aren’t immediately useful to humans. Alert templates transform these payloads into more readable formats and control how the system processes alerts.

Alert templates help you:

- Format alerts for better readability across different notification channels
- Customize alert appearance based on severity or source
- Control alert grouping behavior
- Set up auto-resolution and auto-acknowledgment criteria
- Provide context and actionable information for responders

## Understanding alert payloads

Before creating templates, it’s important to understand the structure of your alert payloads. All alerts in Grafana IRM contain the following standard fields:

- `Title` - The alert name or summary
- `Message` - Detailed information about the alert
- `Image Url` - URL to a visual representation (graph, screenshot)
- `Grouping Id` - Identifier used for grouping related alerts
- `Resolved by source` - Flag indicating if the source system marked the alert as resolved
- `Acknowledged by source` - Flag indicating if the source system acknowledged the alert
- `Source link` - URL to the source system

### Example alert payload

Here’s an example of an alert payload from Grafana Alerting:

JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```json
{
  "dashboardId": 1,
  "title": "[Alerting] Panel Title alert",
  "message": "Notification Message",
  "evalMatches": [
    {
      "value": 1,
      "metric": "Count",
      "tags": {}
    }
  ],
  "imageUrl": "https://grafana.com/static/assets/img/blog/mixed_styles.png",
  "orgId": 1,
  "panelId": 2,
  "ruleId": 1,
  "ruleName": "Panel Title alert",
  "ruleUrl": "http://localhost:3000/d/hZ7BuVbWz/test-dashboard?fullscreen\u0026edit\u0026tab=alert\u0026panelId=2\u0026orgId=1",
  "state": "alerting",
  "tags": {
    "tag name": "tag value"
  }
}
```

### Mapping payloads to Grafana IRM fields

Grafana IRM maps JSON payload keys to specific alert fields using templates. For example:

- `{{ payload.title }}` → `Title`
- `{{ payload.message }}` → `Message`
- `{{ payload.imageUrl }}` → `Image Url`

Behavioral mappings control how alerts are processed:

- `{{ payload.ruleId }}` → `Grouping Id`
- `{{ 1 if payload.state == 'OK' else 0 }}` → `Resolve Signal`

## Types of alert templates

Grafana IRM supports several types of templates for different purposes:

### Routing templates

Routing templates determine which escalation chain handles an alert. These templates evaluate incoming alerts based on their content.

Example (route database alerts to the Database team):

![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```none
{{ "database" in payload.title | lower }}
```

> **Note:** Routing templates must evaluate to `True` for the route to be selected.

### Appearance templates

Appearance templates control how alerts appear in different notification channels:

- **Web UI templates**: Control alert display in the Grafana IRM web interface
- **Slack templates**: Format alerts for Slack notifications
- **MS Teams templates**: Format alerts for Microsoft Teams
- **Telegram templates**: Format alerts for Telegram
- **SMS templates**: Format alerts for SMS messages (title only)
- **Phone call templates**: Format alerts for phone calls (title only)
- **Email templates**: Format alerts for email notifications
- **Mobile app templates**: Format alerts for the mobile app

For each notification channel, you can customize:

- `Title` - The alert headline
- `Message` - The detailed description
- `Image URL` - A visual representation (where supported)

### Behavioral templates

Behavioral templates control how alerts function within Grafana IRM:

- **Grouping Id**: Determines how alerts are grouped together
- **Auto resolution**: Controls when alerts are automatically resolved
- **Auto acknowledge**: Controls when alerts are automatically acknowledged
- **Source link**: Customizes the URL link to the alert source

## Using `payload` and `labels`

Inside of templates, you have access to two *main* variables directly related to your alert’s payload:

- `payload` - The raw alert data as received from the monitoring system
- `labels` - Structured labels extracted and processed, from the alert data, and based on the Labels Schema you’ve configured for your Integration

This gives you two ways to access alert data:

jinja2 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```jinja2
{# Accessing data through the raw payload #}
{{ payload.labels.environment }}

{# Accessing the same data through processed labels #}
{{ labels.environment }}
```

## Edit templates

To customize alert templates:

01. Navigate to the **Integrations** page and select the integration.
02. Scroll to the **Templates** section and click **Edit**.
03. Select the template type you want to modify.
04. The template editor provides three columns:
    
    - Left: Example alert payload
    - Middle: Template editor
    - Right: Rendered result
05. To work with real data, select a **Recent Alert group** from the dropdown.
06. To test with custom data, click **Use custom payload**.
07. Press `Control + Enter` in the editor for template suggestions.
08. Click **Cheatsheet** for template examples and syntax guidance.
09. For chatting app templates, click **Save and open Alert Group in ChatOps** to preview the final result.
10. Click **Save** when finished.

## Template best practices

- **Add context to alerts**: Include links to dashboards, documentation, or runbooks.
- **Format for readability**: Use clear headings and structured formatting.
- **Include actionable information**: Add specific steps or commands that responders can use.
- **Use conditional formatting**: Highlight different severity levels with appropriate formatting.
- **Test with real data**: Always verify templates with actual alert payloads.
- **Keep it concise**: Focus on essential information, especially for SMS and phone calls.

### Example: Enhanced alert message template

![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```none
{% set severity = payload.labels.severity | default('unknown') %}

**{{ payload.alertname }}**
{% if severity == 'critical' %}🔴 CRITICAL{% elif severity == 'warning' %}🟠 WARNING{% else %}ℹ️ INFO{% endif %}

**Details:**
- Service: {{ payload.labels.service | default('N/A') }}
- Instance: {{ payload.labels.instance | default('N/A') }}
- Value: {{ payload.value | default('N/A') }} {{ payload.unit | default('') }}

**Runbook:** {{ payload.annotations.runbook_url | default('No runbook available') }}

**Dashboard:** {{ payload.generatorURL | default('N/A') }}
```

## Next steps

- [Configure escalation chains](/docs/grafana-cloud/alerting-and-irm/irm/escalation-and-routing/escalation-chains) to determine who receives notifications
- [Configure routing rules](/docs/grafana-cloud/alerting-and-irm/irm/escalation-and-routing/routing-rules) to direct alerts to the appropriate teams
- [Learn about incoming webhooks](/docs/grafana-cloud/alerting-and-irm/irm/integrations/custom-integrations/incoming-webhooks) to receive alerts from external systems