# Grouped alerts

If a shared dependency goes down (a data center, a DNS provider, a load balancer) several of your monitors can
fail within moments of each other. Sending a separate alert for every one of them would flood a chat channel or
inbox right when you most need a clear picture. **Grouped alerts** combine alerts that fire close together for
the same contact into a single message listing what happened.

## What it is and when to use it

Turn it on for a contact that watches many monitors and would otherwise get spammed during a correlated
incident (a team channel, a shared inbox). Leave it off for a contact that should see every event as its own
message, or that's already low-volume enough that grouping wouldn't help.

## Settings reference

| Setting (UI label) | API field (v2) | Type / allowed values | Default | Plan limits | What it does for you |
|---|---|---|---|---|---|
| Digest (Email) / Group events (HTTP-family) | `groupedAlerts` | boolean | Email: `true` (in the app and when `POST /contact` leaves it out); HTTP-family: `false` | - | Opt this contact into coalescing close-together alerts into one message |

`groupedAlerts` is a plain boolean on every contact type, but the app's editor only shows a toggle for it on
**Email** (labeled **Digest**) and **HTTP-family** contacts (Slack, Teams, Mattermost, PagerDuty, Opsgenie,
Pushover, Pushbullet, or a plain webhook - labeled **Group events**, shown once the payload format is JSON).
For every other type there's no toggle in the app, but the field is still there on the wire if you want to set
it directly through the API.

## How grouping actually works

Grouping happens per contact, at the moment an alert would be sent - HostTracker holds a short window open for
that contact and folds whatever else fires into one combined message:

- **The window is 70 seconds** for Email, SMS and voice call contacts, and **40 seconds** for everything else
  (chat/webhook channels).
- **Email and voice call buffer the whole window** before sending - you get one message, however many events
  landed in it. **Every other channel (SMS, chat, webhook) sends the first event immediately** and then folds
  anything else that arrives during the window into a short follow-up, so you're never left wondering if
  anything happened while waiting for a digest.
- **On-call channels never group, regardless of this setting.** PagerDuty and Opsgenie always send each Down
  and Up as its own event the instant it fires - grouping would hide exactly the signal an on-call tool exists
  to surface.
- **A plain webhook contact coalesces differently**: instead of the buffered-window mechanism above, several
  alerts due at once are combined into a single HTTP request (a JSON array of events) at the transport level.
  A **custom template** ([see the webhook page](/alerts/channels/webhook/#request-template-configuration))
  always sends one request per event and ignores grouping, since a custom template describes exactly one
  event's shape.

## Set it up in the app

1. Open the contact and expand **Main Settings**.
2. For Email, toggle **Digest**. For an HTTP-family contact with a JSON payload, toggle **Group events** in
   the **Request Template Configuration** group.
3. Save.

## Do it with the API or MCP

```
PATCH /contact/{id}
{ "groupedAlerts": true }
```

There's no dedicated MCP tool for this one field - use `update_contact(id, groupedAlerts=true)`.

## What happens next

The next time two or more alerts land for this contact within its window, they arrive as one combined message
instead of separate ones. A single alert with nothing else in its window is unaffected either way.

## Limits and gotchas

- Grouping is evaluated **per contact**, not per monitor or per subscription - turning it on affects every
  alert that contact would otherwise receive individually.
- It has no effect on **when** an alert fires - [alert delay](/alerts/escalation/) and
  [active hours](/alerts/active-hours/) still gate delivery first; grouping only changes how already-eligible
  alerts for the same contact are packaged.
- On-call channels (PagerDuty, Opsgenie) ignore this setting outright - there's no way to make them group.

## Related

- [Alert delays & escalation](/alerts/escalation/)
- [Set up each channel](/alerts/channels/)
- [PagerDuty](/alerts/channels/pagerduty/) - [Opsgenie](/alerts/channels/opsgenie/)
- [Webhook](/alerts/channels/webhook/)