---
title: Discord notifier
description: Discord webhook with rich embeds, retry handling, and thread support.
---

<div style={{ display: "flex", alignItems: "center", gap: "0.75rem", margin: "0.5rem 0 1.25rem" }}>
  <Logo name="discord" size={28} color />
  <span style={{ fontSize: "0.8125rem", color: "var(--color-fd-muted-foreground)" }}>
    Slot: <code>notifier</code> · Name: <code>discord</code>
  </span>
</div>

<PlatformSupport macos="full" linux="full" windows="full" />

## Setup

Run the setup command:

```bash
ao setup discord
```

If Discord is already configured, the command asks whether to keep the existing
webhook URL, change it, create a new one, or cancel. If you already have a
Discord webhook URL, paste it when prompted. If not, the command shows Discord
links and waits while you create one. From the setup steps screen you can paste
the URL, show the steps again, go back to the previous options, or cancel. The
change-webhook path also lets you paste a new URL, view creation steps, go back,
or cancel.

1. Open **https://discord.com/app**.
2. Open the target server and channel.
3. Open **Edit Channel → Integrations → Webhooks**.
4. Create a new webhook.
5. Copy the webhook URL and paste it into AO.

The command sends a test message before writing AO config.
Before saving, AO also asks which notification priorities Discord should receive:
`urgent-only`, `urgent-action`, or `all`. For scriptable setup, pass
`--routing-preset <preset>`.

Useful setup checks:

```bash
ao setup discord --status
ao setup discord --refresh
```

```yaml title="agent-orchestrator.yaml"
notifiers:
  discord:
    plugin: discord
    webhookUrl: https://discord.com/api/webhooks/...
    username: "Agent Orchestrator"
    avatarUrl: https://...png # optional
    threadId: "1234567890" # optional; post into a thread
    retries: 2
    retryDelayMs: 1000
```

## Config

| Key            | Required | Default              | What it does                                                        |
| -------------- | -------- | -------------------- | ------------------------------------------------------------------- |
| `webhookUrl`   | ✓        | —                    | Full `discord.com/api/webhooks/...` URL bound to the target channel |
| `username`     | optional | `Agent Orchestrator` | Override webhook default username per message                       |
| `avatarUrl`    | optional | —                    | Override webhook default avatar with an image URL                   |
| `threadId`     | optional | —                    | Post into an existing thread                                        |
| `retries`      | optional | `2`                  | Retry count on 429 / 5xx / network errors                           |
| `retryDelayMs` | optional | `1000`               | Base retry delay (exponential backoff)                              |

Discord webhook URLs are tied to the channel selected in Discord. To send to a
different channel, create or copy a webhook URL from that channel.

## Rich embeds

AO uses Discord embeds, not plain text. Each event shows:

- Colored sidebar (blue for info, red for CI failure, amber for review requested, green for merged)
- Issue / PR link as a clickable title
- Session id as a field
- Short reason as the description

## Retry + rate limiting

Handles Discord's `Retry-After` header on 429 responses — waits the requested interval and retries. 5xx errors use exponential backoff up to `retries` attempts.

## Testing

```bash
ao notify test --to discord --template basic
ao notify test --to discord --template merge-ready --actions
```
