> ## Documentation Index
> Fetch the complete documentation index at: https://piloop.autoresearch.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Notifications

> Get a Slack message when an escalation waits for you.

A **notifier** tells you, outside piloop, that an inbox item needs you. To post to a Slack channel, create an
[incoming webhook](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks), store its URL as a
[secret](https://piloop.autoresearch.inc/guides/secrets.md), and name `slack` in `config.toml`:

```bash theme={null}
printf %s "$SLACK_WEBHOOK_URL" | piloop secret set SLACK_WEBHOOK_URL
```

```text theme={null}
SLACK_WEBHOOK_URL set for the home
```

```toml theme={null}
# $PILOOP_HOME/config.toml
[plugins.notifier]
use = ["slack"]
```

Then run `piloop restart`. The next escalation posts this to the channel:

```text theme={null}
:rotating_light: *enwik8* · escalation comment#1 · P1 · from implementer#12
Run 41's evaluation takes 3 h, over the 1 h timeout. Raise the timeout, or drop the idea?
`piloop inbox show 1`
```

## What is sent

* An item is sent when it is an escalation or has priority 0, nobody has acknowledged it, and a person did not write
  it.
* Each pass of the daemon sends one message with every new item.
* An item that still waits a day later is sent again as a reminder. `piloop inbox ack` ends the reminders.
* piloop records each send as a `notification.sent` event on the item, so a restart sends nothing twice.

## When a send fails

piloop records a `notification.failed` event with the error, and tries again after 1 minute, then 2, 4 and so on, up
to an hour. Slack's `Retry-After` wins. The first failure also puts a note in your inbox, under the item that was not
sent.

## A channel of your own

Name an instance to change its keys. A notifier that `use` does not name is an error.

```toml theme={null}
[plugins.notifier]
use = ["team"]

[plugins.notifier.team]
provider = "slack"
webhook = { secret = "TEAM_WEBHOOK" }
link = "https://piloop.example.com/inbox/{comment}"
mentions = { "alice@example.com" = "U0123ABC" }
remind_every = "PT12H"
template = "{mark} *{campaign}* {kind} from {author}{mention}\n{body}\n{link}"
```

`template` sets how the message shows each item, from a fixed set of placeholders: an unknown one is an error when
the file loads. On a shared server, `mentions` pings the person who added the campaign, by the name that the server
gives them.
The [configuration reference](https://piloop.autoresearch.inc/reference/configuration.md#plugins) lists every key of `slack`.

To write a notifier for another service, see [Infrastructure](https://piloop.autoresearch.inc/plugins/infrastructure.md#notifiers).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.