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

# Discord

# Discord (Bot API)

Status: ready for DMs and guild channels via the official Discord gateway.

> [card] [Pairing](https://docs.wednesdayai.dev/next/admin/channels/pairing.md)
>
> Discord DMs default to pairing mode.

> [card] [Slash commands](https://docs.wednesdayai.dev/next/users/tools/slash-commands.md)
>
> Native command behavior and command catalog.

> [card] [Channel troubleshooting](https://docs.wednesdayai.dev/next/admin/channels/troubleshooting.md)
>
> Cross-channel diagnostics and repair flow.

## Quick setup

You will need to create a new application with a bot, add the bot to your server, and pair it to WednesdayAI. We recommend adding your bot to your own private server. If you don't have one yet, [create one first](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server) (choose **Create My Own > For me and my friends**).

**1. Create a Discord application and bot**

Go to the [Discord Developer Portal](https://discord.com/developers/applications) and click **New Application**. Name it something like "WednesdayAI".

Click **Bot** on the sidebar. Set the **Username** to whatever you call your WednesdayAI agent.

**2. Enable privileged intents**

Still on the **Bot** page, scroll down to **Privileged Gateway Intents** and enable:

* **Message Content Intent** (required)
* **Server Members Intent** (recommended; required for role allowlists and name-to-ID matching)
* **Presence Intent** (optional; only needed for presence updates)

**3. Copy your bot token**

Scroll back up on the **Bot** page and click **Reset Token**.

> [!NOTE]
>
> Despite the name, this generates your first token — nothing is being "reset."

Copy the token and save it somewhere. This is your **Bot Token** and you will need it shortly.

**4. Generate an invite URL and add the bot to your server**

Click **OAuth2** on the sidebar. You'll generate an invite URL with the right permissions to add the bot to your server.

Scroll down to **OAuth2 URL Generator** and enable:

* `bot`
* `applications.commands`

A **Bot Permissions** section will appear below. Enable:

* View Channels
* Send Messages
* Read Message History
* Embed Links
* Attach Files
* Add Reactions (optional)

Copy the generated URL at the bottom, paste it into your browser, select your server, and click **Continue** to connect. You should now see your bot in the Discord server.

**5. Enable Developer Mode and collect your IDs**

Back in the Discord app, you need to enable Developer Mode so you can copy internal IDs.

1. Click **User Settings** (gear icon next to your avatar) → **Advanced** → toggle on **Developer Mode**
2. Right-click your **server icon** in the sidebar → **Copy Server ID**
3. Right-click your **own avatar** → **Copy User ID**

Save your **Server ID** and **User ID** alongside your Bot Token — you'll send all three to WednesdayAI in the next step.

**6. Allow DMs from server members**

For pairing to work, Discord needs to allow your bot to DM you. Right-click your **server icon** → **Privacy Settings** → toggle on **Direct Messages**.

This lets server members (including bots) send you DMs. Keep this enabled if you want to use Discord DMs with WednesdayAI. If you only plan to use guild channels, you can disable DMs after pairing.

**7. Step 0: Set your bot token securely (do not send it in chat)**

Your Discord bot token is a secret (like a password). Set it on the machine running WednesdayAI before messaging your agent.

```bash theme={"dark"}
wednesdayai config set channels.discord.token '"YOUR_BOT_TOKEN"' --json
wednesdayai config set channels.discord.enabled true --json
wednesdayai gateway run
```

If WednesdayAI is already running as a background service, use `wednesdayai gateway restart` instead.

**8. Configure WednesdayAI and pair**

> [tab] Ask your agent
>
> Chat with your WednesdayAI agent on any existing channel (e.g. Telegram) and tell it. If Discord is your first channel, use the CLI / config tab instead.
>
> > "I already set my Discord bot token in config. Please finish Discord setup with User ID `<user_id>` and Server ID `<server_id>`."

> [tab] CLI / config
>
> If you prefer file-based config, set:
>
> ```json5 theme={"dark"}
> {
>   channels: {
>     discord: {
>       enabled: true,
>       token: "YOUR_BOT_TOKEN",
>     },
>   },
> }
> ```
>
> Env fallback for the default account:
>
> ```bash theme={"dark"}
> DISCORD_BOT_TOKEN=...
> ```

**9. Approve first DM pairing**

Wait until the gateway is running, then DM your bot in Discord. It will respond with a pairing code.

> [tab] Ask your agent
>
> Send the pairing code to your agent on your existing channel:
>
> > "Approve this Discord pairing code: `<CODE>`"

> [tab] CLI
>
> ```bash theme={"dark"}
> wednesdayai pairing list discord
> wednesdayai pairing approve discord <CODE>
> ```

Pairing codes expire after 1 hour.

You should now be able to chat with your agent in Discord via DM.

> [!NOTE]
>
> Token resolution is account-aware. Config token values win over env fallback. `DISCORD_BOT_TOKEN` is only used for the default account.

## Recommended: Set up a guild workspace

Once DMs are working, you can set up your Discord server as a full workspace where each channel gets its own agent session with its own context. This is recommended for private servers where it's just you and your bot.

**1. Add your server to the guild allowlist**

This enables your agent to respond in any channel on your server, not just DMs.

> [tab] Ask your agent
>
> > "Add my Discord Server ID `<server_id>` to the guild allowlist"

> [tab] Config
>
> ```json5 theme={"dark"}
> {
>   channels: {
>     discord: {
>       groupPolicy: "allowlist",
>       guilds: {
>         YOUR_SERVER_ID: {
>           requireMention: true,
>           users: ["YOUR_USER_ID"],
>         },
>       },
>     },
>   },
> }
> ```

**2. Allow responses without @mention**

By default, your agent only responds in guild channels when @mentioned. For a private server, you probably want it to respond to every message.

> [tab] Ask your agent
>
> > "Allow my agent to respond on this server without having to be @mentioned"

> [tab] Config
>
> Set `requireMention: false` in your guild config:
>
> ```json5 theme={"dark"}
> {
>   channels: {
>     discord: {
>       guilds: {
>         YOUR_SERVER_ID: {
>           requireMention: false,
>         },
>       },
>     },
>   },
> }
> ```

**3. Plan for memory in guild channels**

By default, long-term memory (MEMORY.md) only loads in DM sessions. Guild channels do not auto-load MEMORY.md.

> [tab] Ask your agent
>
> > "When I ask questions in Discord channels, use memory\_search or memory\_get if you need long-term context from MEMORY.md."

> [tab] Manual
>
> If you need shared context in every channel, put the stable instructions in `AGENTS.md` or `USER.md` (they are injected for every session). Keep long-term notes in `MEMORY.md` and access them on demand with memory tools.

Now create some channels on your Discord server and start chatting. Your agent can see the channel name, and each channel gets its own isolated session — so you can set up `#coding`, `#home`, `#research`, or whatever fits your workflow.

## Runtime model

* Gateway owns the Discord connection.
* Reply routing is deterministic: Discord inbound replies back to Discord.
* By default (`session.dmScope=main`), direct chats share the agent main session (`agent:main:main`).
* Guild channels are isolated session keys (`agent:<agentId>:discord:channel:<channelId>`).
* Group DMs are ignored by default (`channels.discord.dm.groupEnabled=false`).
* Native slash commands run in isolated command sessions (`agent:<agentId>:discord:slash:<userId>`), while still carrying `CommandTargetSessionKey` to the routed conversation session.

## Forum channels

Discord forum and media channels only accept thread posts. WednesdayAI supports two ways to create them:

* Send a message to the forum parent (`channel:<forumId>`) to auto-create a thread. The thread title uses the first non-empty line of your message.
* Use `wednesdayai message thread create` to create a thread directly. Do not pass `--message-id` for forum channels.

Example: send to forum parent to create a thread

```bash theme={"dark"}
wednesdayai message send --channel discord --target channel:<forumId> \
  --message "Topic title\nBody of the post"
```

Example: create a forum thread explicitly

```bash theme={"dark"}
wednesdayai message thread create --channel discord --target channel:<forumId> \
  --thread-name "Topic title" --message "Body of the post"
```

Forum parents do not accept Discord components. If you need components, send to the thread itself (`channel:<threadId>`).

## Interactive components

WednesdayAI supports Discord components v2 containers for agent messages. Use the message tool with a `components` payload. Interaction results are routed back to the agent as normal inbound messages and follow the existing Discord `replyToMode` settings.

Supported blocks:

* `text`, `section`, `separator`, `actions`, `media-gallery`, `file`
* Action rows allow up to 5 buttons or a single select menu
* Select types: `string`, `user`, `role`, `mentionable`, `channel`

By default, components are single use. Set `components.reusable=true` to allow buttons, selects, and forms to be used multiple times until they expire.

To restrict who can click a button, set `allowedUsers` on that button (Discord user IDs, tags, or `*`). When configured, unmatched users receive an ephemeral denial.

The `/model` and `/models` slash commands open an interactive model picker with provider and model dropdowns plus a Submit step. The picker reply is ephemeral and only the invoking user can use it.

File attachments:

* `file` blocks must point to an attachment reference (`attachment://<filename>`)
* Provide the attachment via `media`/`path`/`filePath` (single file); use `media-gallery` for multiple files
* Use `filename` to override the upload name when it should match the attachment reference

Modal forms:

* Add `components.modal` with up to 5 fields
* Field types: `text`, `checkbox`, `radio`, `select`, `role-select`, `user-select`
* WednesdayAI adds a trigger button automatically

Example:

```json5 theme={"dark"}
{
  channel: "discord",
  action: "send",
  to: "channel:123456789012345678",
  message: "Optional fallback text",
  components: {
    reusable: true,
    text: "Choose a path",
    blocks: [
      {
        type: "actions",
        buttons: [
          {
            label: "Approve",
            style: "success",
            allowedUsers: ["123456789012345678"],
          },
          { label: "Decline", style: "danger" },
        ],
      },
      {
        type: "actions",
        select: {
          type: "string",
          placeholder: "Pick an option",
          options: [
            { label: "Option A", value: "a" },
            { label: "Option B", value: "b" },
          ],
        },
      },
    ],
    modal: {
      title: "Details",
      triggerLabel: "Open form",
      fields: [
        { type: "text", label: "Requester" },
        {
          type: "select",
          label: "Priority",
          options: [
            { label: "Low", value: "low" },
            { label: "High", value: "high" },
          ],
        },
      ],
    },
  },
}
```

## Access control and routing

> [tab] DM policy
>
> `channels.discord.dmPolicy` controls DM access (legacy: `channels.discord.dm.policy`):
>
> * `pairing` (default)
> * `allowlist`
> * `open` (requires `channels.discord.allowFrom` to include `"*"`; legacy: `channels.discord.dm.allowFrom`)
> * `disabled`
>
> If DM policy is not open, unknown users are blocked (or prompted for pairing in `pairing` mode).
>
> Multi-account precedence:
>
> * `channels.discord.accounts.default.allowFrom` applies only to the `default` account.
> * Named accounts inherit `channels.discord.allowFrom` when their own `allowFrom` is unset.
> * Named accounts do not inherit `channels.discord.accounts.default.allowFrom`.
>
> DM target format for delivery:
>
> * `user:<id>`
> * `<@id>` mention
>
> Bare numeric IDs are ambiguous and rejected unless an explicit user/channel target kind is provided.

> [tab] Guild policy
>
> Guild handling is controlled by `channels.discord.groupPolicy`:
>
> * `open`
> * `allowlist`
> * `disabled`
>
> Secure baseline when `channels.discord` exists is `allowlist`.
>
> `allowlist` behavior:
>
> * guild must match `channels.discord.guilds` (`id` preferred, slug accepted)
> * optional sender allowlists: `users` (stable IDs recommended) and `roles` (role IDs only); if either is configured, senders are allowed when they match `users` OR `roles`
> * direct name/tag matching is disabled by default; enable `channels.discord.dangerouslyAllowNameMatching: true` only as break-glass compatibility mode
> * names/tags are supported for `users`, but IDs are safer; `wednesdayai security audit` warns when name/tag entries are used
> * if a guild has `channels` configured, non-listed channels are denied
> * if a guild has no `channels` block, all channels in that allowlisted guild are allowed
>
> Example:
>
> ```json5 theme={"dark"}
> {
>   channels: {
>     discord: {
>       groupPolicy: "allowlist",
>       guilds: {
>         "123456789012345678": {
>           requireMention: true,
>           users: ["987654321098765432"],
>           roles: ["123456789012345678"],
>           channels: {
>             general: { allow: true },
>             help: { allow: true, requireMention: true },
>           },
>         },
>       },
>     },
>   },
> }
> ```
>
> If you only set `DISCORD_BOT_TOKEN` and do not create a `channels.discord` block, runtime fallback is `groupPolicy="allowlist"` (with a warning in logs), even if `channels.defaults.groupPolicy` is `open`.

> [tab] Mentions and group DMs
>
> Guild messages are mention-gated by default.
>
> Mention detection includes:
>
> * explicit bot mention
> * configured mention patterns (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
> * implicit reply-to-bot behavior in supported cases
>
> `requireMention` is configured per guild/channel (`channels.discord.guilds...`).
>
> Group DMs:
>
> * default: ignored (`dm.groupEnabled=false`)
> * optional allowlist via `dm.groupChannels` (channel IDs or slugs)
>
> Multi-account precedence:
>
> * `channels.discord.accounts.default.allowFrom` applies only to the `default` account.
> * Named accounts inherit `channels.discord.allowFrom` when their own `allowFrom` is unset.
> * Named accounts do not inherit `channels.discord.accounts.default.allowFrom`.

### Role-based agent routing

Use `bindings[].match.roles` to route Discord guild members to different agents by role ID. Role-based bindings accept role IDs only and are evaluated after peer or parent-peer bindings and before guild-only bindings. If a binding also sets other match fields (for example `peer` + `guildId` + `roles`), all configured fields must match.

```json5 theme={"dark"}
{
  bindings: [
    {
      agentId: "opus",
      match: {
        channel: "discord",
        guildId: "123456789012345678",
        roles: ["111111111111111111"],
      },
    },
    {
      agentId: "sonnet",
      match: {
        channel: "discord",
        guildId: "123456789012345678",
      },
    },
  ],
}
```

## Developer Portal setup

> [accordion] Create app and bot
>
> 1. Discord Developer Portal -> **Applications** -> **New Application**
> 2. **Bot** -> **Add Bot**
> 3. Copy bot token

> [accordion] Privileged intents
>
> In **Bot -> Privileged Gateway Intents**, enable:
>
> * Message Content Intent
> * Server Members Intent (recommended)
>
> Presence intent is optional and only required if you want to receive presence updates. Setting bot presence (`setPresence`) does not require enabling presence updates for members.
>
> WednesdayAI config for privileged intents:
>
> ```json5 theme={"dark"}
> {
>   channels: {
>     discord: {
>       intents: {
>         presence: false,      // Guild Presences intent (requires Portal opt-in)
>         guildMembers: false,  // Guild Members intent (requires Portal opt-in)
>       },
>     },
>   },
> }
> ```

> [accordion] OAuth scopes and baseline permissions
>
> OAuth URL generator:
>
> * scopes: `bot`, `applications.commands`
>
> Typical baseline permissions:
>
> * View Channels
> * Send Messages
> * Read Message History
> * Embed Links
> * Attach Files
> * Add Reactions (optional)
>
> Avoid `Administrator` unless explicitly needed.

> [accordion] Copy IDs
>
> Enable Discord Developer Mode, then copy:
>
> * server ID
> * channel ID
> * user ID
>
> Prefer numeric IDs in WednesdayAI config for reliable audits and probes.

## Native commands and command auth

* `commands.native` defaults to `"auto"` and is enabled for Discord.
* Per-channel override: `channels.discord.commands.native`.
* `commands.native=false` explicitly clears previously registered Discord native commands.
* Native command auth uses the same Discord allowlists/policies as normal message handling.
* Commands may still be visible in Discord UI for users who are not authorized; execution still enforces WednesdayAI auth and returns "not authorized".

See [Slash commands](https://docs.wednesdayai.dev/next/users/tools/slash-commands.md) for command catalog and behavior.

Default slash command settings:

* `ephemeral: true`

## Feature details

> [accordion] Reply tags and native replies
>
> Discord supports reply tags in agent output:
>
> * `[[reply_to_current]]`
> * `[[reply_to:<id>]]`
>
> Controlled by `channels.discord.replyToMode`:
>
> * `off` (default)
> * `first`
> * `all`
>
> Note: `off` disables implicit reply threading. Explicit `[[reply_to_*]]` tags are still honored.
>
> Message IDs are surfaced in context/history so agents can target specific messages.

> [accordion] Live stream preview
>
> WednesdayAI can stream draft replies by sending a temporary message and editing it as text arrives.
>
> * `channels.discord.streaming` controls preview streaming (`off` | `partial` | `block` | `progress`, default: `off`).
> * `progress` is accepted for cross-channel consistency and maps to `partial` on Discord.
> * `channels.discord.streamMode` is a legacy alias and is auto-migrated.
> * `partial` edits a single preview message as tokens arrive.
> * `block` emits draft-sized chunks (use `draftChunk` to tune size and breakpoints).
>
> Example:
>
> ```json5 theme={"dark"}
> {
>   channels: {
>     discord: {
>       streaming: "partial",
>     },
>   },
> }
> ```
>
> `block` mode chunking defaults (clamped to `channels.discord.textChunkLimit`):
>
> ```json5 theme={"dark"}
> {
>   channels: {
>     discord: {
>       streaming: "block",
>       draftChunk: {
>         minChars: 200,
>         maxChars: 800,
>         breakPreference: "paragraph",
>       },
>     },
>   },
> }
> ```
>
> Preview streaming is text-only; media replies fall back to normal delivery.
>
> Note: preview streaming is separate from block streaming. When block streaming is explicitly
> enabled for Discord, WednesdayAI skips the preview stream to avoid double streaming.

> [accordion] History, context, and thread behavior
>
> Guild history context:
>
> * `channels.discord.historyLimit` default `20`
> * fallback: `messages.groupChat.historyLimit`
> * `0` disables
>
> DM history controls:
>
> * `channels.discord.dmHistoryLimit`
> * `channels.discord.dms["<user_id>"].historyLimit`
>
> Thread behavior:
>
> * Discord threads are routed as channel sessions
> * parent thread metadata can be used for parent-session linkage
> * thread config inherits parent channel config unless a thread-specific entry exists
>
> Channel topics are injected as **untrusted** context (not as system prompt).

> [accordion] Thread-bound sessions for subagents
>
> Discord can bind a thread to a session target so follow-up messages in that thread keep routing to the same session (including subagent sessions).
>
> Commands:
>
> * `/focus <target>` bind current/new thread to a subagent/session target
> * `/unfocus` remove current thread binding
> * `/agents` show active runs and binding state
> * `/session idle <duration|off>` inspect/update inactivity auto-unfocus for focused bindings
> * `/session max-age <duration|off>` inspect/update hard max age for focused bindings
>
> Config:
>
> ```json5 theme={"dark"}
> {
>   session: {
>     threadBindings: {
>       enabled: true,
>       idleHours: 24,
>       maxAgeHours: 0,
>     },
>   },
>   channels: {
>     discord: {
>       threadBindings: {
>         enabled: true,
>         idleHours: 24,
>         maxAgeHours: 0,
>         spawnSubagentSessions: false, // opt-in
>       },
>     },
>   },
> }
> ```
>
> Notes:
>
> * `session.threadBindings.*` sets global defaults.
> * `channels.discord.threadBindings.*` overrides Discord behavior.
> * `spawnSubagentSessions` must be true to auto-create/bind threads for `sessions_spawn({ thread: true })`.
> * `spawnAcpSessions` must be true to auto-create/bind threads for ACP (`/acp spawn ... --thread ...` or `sessions_spawn({ runtime: "acp", thread: true })`).
> * If thread bindings are disabled for an account, `/focus` and related thread binding operations are unavailable.
>
> See [Sub-agents](https://docs.wednesdayai.dev/next/users/tools/subagents.md), [ACP Agents](https://docs.wednesdayai.dev/next/users/tools/acp-agents.md), and [Configuration Reference](https://docs.wednesdayai.dev/next/admin/gateway/configuration-reference.md).

> [accordion] Reaction notifications
>
> Per-guild reaction notification mode:
>
> * `off`
> * `own` (default)
> * `all`
> * `allowlist` (uses `guilds.<id>.users`)
>
> Reaction events are turned into system events and attached to the routed Discord session.

> [accordion] Ack reactions
>
> `ackReaction` sends an acknowledgement emoji while WednesdayAI is processing an inbound message.
>
> Resolution order:
>
> * `channels.discord.accounts.<accountId>.ackReaction`
> * `channels.discord.ackReaction`
> * `messages.ackReaction`
> * agent identity emoji fallback (`agents.list[].identity.emoji`, else "👀")
>
> Scope control via `channels.discord.ackReactionScope`:
>
> * `group-mentions` — only in group chats when mentioned
> * `group-all` — in all group chat messages
> * `direct` — only in DMs
> * `all` — in all chats
> * `off` / `none` — disabled
>
> Notes:
>
> * Discord accepts unicode emoji or custom emoji names.
> * Use `""` to disable the reaction for a channel or account.

> [accordion] Config writes
>
> Channel-initiated config writes are enabled by default.
>
> This affects `/config set|unset` flows (when command features are enabled).
>
> Disable:
>
> ```json5 theme={"dark"}
> {
>   channels: {
>     discord: {
>       configWrites: false,
>     },
>   },
> }
> ```

> [accordion] Gateway proxy
>
> Route Discord gateway WebSocket traffic and startup REST lookups (application ID + allowlist resolution) through an HTTP(S) proxy with `channels.discord.proxy`.
>
> ```json5 theme={"dark"}
> {
>   channels: {
>     discord: {
>       proxy: "http://proxy.example:8080",
>     },
>   },
> }
> ```
>
> Per-account override:
>
> ```json5 theme={"dark"}
> {
>   channels: {
>     discord: {
>       accounts: {
>         primary: {
>           proxy: "http://proxy.example:8080",
>         },
>       },
>     },
>   },
> }
> ```

> [accordion] PluralKit support
>
> Enable PluralKit resolution to map proxied messages to system member identity:
>
> ```json5 theme={"dark"}
> {
>   channels: {
>     discord: {
>       pluralkit: {
>         enabled: true,
>         token: "pk_live_...", // optional; needed for private systems
>       },
>     },
>   },
> }
> ```
>
> Notes:
>
> * allowlists can use `pk:<memberId>`
> * member display names are matched by name/slug only when `channels.discord.dangerouslyAllowNameMatching: true`
> * lookups use original message ID and are time-window constrained
> * if lookup fails, proxied messages are treated as bot messages and dropped unless `allowBots=true`

> [accordion] Presence configuration
>
> Presence updates are applied only when you set a status or activity field.
>
> Status only example:
>
> ```json5 theme={"dark"}
> {
>   channels: {
>     discord: {
>       status: "idle",
>     },
>   },
> }
> ```
>
> Activity example (custom status is the default activity type):
>
> ```json5 theme={"dark"}
> {
>   channels: {
>     discord: {
>       activity: "Focus time",
>       activityType: 4,
>     },
>   },
> }
> ```
>
> Streaming example:
>
> ```json5 theme={"dark"}
> {
>   channels: {
>     discord: {
>       activity: "Live coding",
>       activityType: 1,
>       activityUrl: "https://twitch.tv/openclaw",
>     },
>   },
> }
> ```
>
> Activity type map:
>
> * 0: Playing
> * 1: Streaming (requires `activityUrl`)
> * 2: Listening
> * 3: Watching
> * 4: Custom (uses the activity text as the status state; emoji is optional)
> * 5: Competing

> [accordion] Exec approvals in Discord
>
> Discord supports button-based exec approvals in DMs and can optionally post approval prompts in the originating channel.
>
> Config path:
>
> * `channels.discord.execApprovals.enabled`
> * `channels.discord.execApprovals.approvers`
> * `channels.discord.execApprovals.target` (`dm` | `channel` | `both`, default: `dm`)
> * `agentFilter`, `sessionFilter`, `cleanupAfterResolve`
>
> When `target` is `channel` or `both`, the approval prompt is visible in the channel. Only configured approvers can use the buttons; other users receive an ephemeral denial. Approval prompts include the command text, so only enable channel delivery in trusted channels. The channel prompt targets the conversation's stored delivery route (the channel and recipient recorded on the session row, with the turn source taking precedence); when the session has no stored route, WednesdayAI falls back to DM delivery.
>
> If approvals fail with unknown approval IDs, verify approver list and feature enablement.
>
> Related docs: [Exec approvals](https://docs.wednesdayai.dev/next/users/tools/exec-approvals.md)

> [accordion] Reaction notifications
>
> Discord supports per-guild reaction notification mode:
>
> * `channels.discord.guilds.<guildId>.reactionNotifications`: `off | own | all | allowlist` (default: `own`)
> * `off`: ignore all reactions
> * `own`: notify when users react to bot-sent messages
> * `all`: notify agent of all reactions
> * `allowlist`: notify only for reactions from users in the guild allowlist
>
> Config example:
>
> ```json5 theme={"dark"}
> {
>   channels: {
>     discord: {
>       guilds: {
>         "<guild-id>": {
>           reactionNotifications: "all",
>         },
>       },
>     },
>   },
> }
> ```
>
> Reaction events still respect Discord access controls (guild policy, allowlists); unauthorized senders are dropped.

## Tools and action gates

Discord message actions include messaging, channel admin, moderation, presence, and metadata actions.

Core examples:

* messaging: `sendMessage`, `readMessages`, `editMessage`, `deleteMessage`, `threadReply`
* reactions: `react`, `reactions`, `emojiList`
* moderation: `timeout`, `kick`, `ban`
* presence: `setPresence`

Action gates live under `channels.discord.actions.*`.

Default gate behavior:

| Action group | Default |
| - | - |
| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | enabled |
| roles | disabled |
| moderation | disabled |
| presence | disabled |

## Components v2 UI

WednesdayAI uses Discord components v2 for exec approvals and cross-context markers. Discord message actions can also accept `components` for custom UI (advanced; requires Carbon component instances), while legacy `embeds` remain available but are not recommended.

* `channels.discord.ui.components.accentColor` sets the accent color used by Discord component containers (hex).
* Set per account with `channels.discord.accounts.<id>.ui.components.accentColor`.
* `embeds` are ignored when components v2 are present.

Example:

```json5 theme={"dark"}
{
  channels: {
    discord: {
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
    },
  },
}
```

## Voice channels

WednesdayAI can join Discord voice channels for realtime, continuous conversations. This is separate from voice message attachments.

Requirements:

* Enable native commands (`commands.native` or `channels.discord.commands.native`).
* Configure `channels.discord.voice`.
* The bot needs Connect + Speak permissions in the target voice channel.
* Inbound voice decoding uses the bundled opusscript (WASM) decoder, so no native Opus build is required.

Use the Discord-only native command `/vc join|leave|status` to control sessions. The command uses the account default agent and follows the same allowlist and group policy rules as other Discord commands.

Auto-join example:

```json5 theme={"dark"}
{
  channels: {
    discord: {
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
    },
  },
}
```

Notes:

* `voice.tts` overrides `messages.tts` for voice playback only. The resolution order is `messages.tts`, then the route agent's `agents.list[].tts`, then `channels.discord.voice.tts`; see [Per-agent TTS](https://docs.wednesdayai.dev/next/users/tts.md#per-agent-tts-agentslisttts).
* Voice transcript turns derive owner status from Discord `allowFrom` (or `dm.allowFrom`); non-owner speakers cannot access owner-only tools (for example `gateway` and `cron`).
* Voice is enabled by default; set `channels.discord.voice.enabled=false` to disable it.
* `voice.daveEncryption` and `voice.decryptionFailureTolerance` pass through to `@discordjs/voice` join options.
* `@discordjs/voice` defaults are `daveEncryption=true` and `decryptionFailureTolerance=24` if unset.
* WednesdayAI also watches receive decrypt failures and auto-recovers by leaving/rejoining the voice channel after repeated failures in a short window.
* If receive logs repeatedly show `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`, this may be the upstream `@discordjs/voice` receive bug tracked in [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419).

## Voice messages

Discord voice messages show a waveform preview and require OGG/Opus audio plus metadata. WednesdayAI generates the waveform automatically, but it needs `ffmpeg` and `ffprobe` available on the gateway host to inspect and convert audio files.

Requirements and constraints:

* Provide a **local file path** (URLs are rejected).
* Omit text content (Discord does not allow text + voice message in the same payload).
* Any audio format is accepted; WednesdayAI converts to OGG/Opus when needed.

Example:

```bash theme={"dark"}
message(action="send", channel="discord", target="channel:123", path="/path/to/audio.mp3", asVoice=true)
```

## Troubleshooting

> [accordion] Used disallowed intents or bot sees no guild messages
>
> * enable Message Content Intent
> * enable Server Members Intent when you depend on user/member resolution
> * restart gateway after changing intents
>
> A gateway close with code 4014 stops the account. `wednesdayai channels status` shows
> `disconnected (code 4014)` and an error naming the missing privileged intents.

> [accordion] Gateway closed with a fatal code (4004, 4010-4014)
>
> Discord closes the gateway with a fatal code when it will not accept the session. The
> gateway marks the account failed at once, and `wednesdayai channels status` shows
> `failed (code N), disconnected (code N)` with `error:gateway closed with code N: <reason>`
> and a warning that names the fix. `wednesdayai doctor` lists the same warning. The gateway
> log records `discord: gateway closed with code N (<reason>); stopping the Discord monitor.`
>
> | Code | Reason in status | What to do |
> | - | - | - |
> | 4004 | authentication failed (check the bot token) | Reset the bot token in the Developer Portal and update `channels.discord.token`. |
> | 4010 | invalid shard | WednesdayAI connects as a single shard; report the code as a bug. |
> | 4011 | sharding required | The bot is in more guilds than one gateway connection holds; WednesdayAI does not shard. |
> | 4012 | invalid gateway API version | WednesdayAI pins the API version; report the code as a bug. |
> | 4013 | invalid intents | WednesdayAI builds the intents from `channels.discord.intents`; report the code as a bug. |
> | 4014 | missing privileged gateway intents | Enable the intents (see the entry above). |
>
> A failed account is not restarted with backoff or by the health monitor. It starts again
> when its resolved config changes: you save a config change for that account (for example
> a new token), or `wednesdayai secrets reload` resolves a new token from a SecretRef (picked
> up at the next health check). `wednesdayai gateway restart` also starts it. Other accounts
> keep running. Disabling the account, or removing its token, clears the failed state;
> status then shows it as disabled or not configured.
>
> If Discord rejects the bot token at startup (HTTP 401), the account fails the same way
> with `failed (code 401)` and `authentication failed: Discord rejected the bot token
>         (HTTP 401)`, before it opens a gateway connection.

> [accordion] Status stays disconnected or connecting
>
> `wednesdayai channels status` reports `connecting` while the gateway session is
> handshaking, `connected` after READY or RESUMED, and `disconnected (<reason>)` with the
> last close code or error. The gateway log records `discord gateway: Gateway websocket
>         opened`, `discord gateway: ready`, close codes, and reconnect scheduling at info level.
>
> If status stays `connecting`, check the log for repeated close or reconnect lines.

> [accordion] Guild messages blocked unexpectedly
>
> * verify `groupPolicy`
> * verify guild allowlist under `channels.discord.guilds`
> * if guild `channels` map exists, only listed channels are allowed
> * verify `requireMention` behavior and mention patterns
>
> Useful checks:
>
> ```bash theme={"dark"}
> wednesdayai doctor
> wednesdayai channels status --probe
> wednesdayai logs --follow
> ```

> [accordion] Require mention false but still blocked
>
> Common causes:
>
> * `groupPolicy="allowlist"` without matching guild/channel allowlist
> * `requireMention` configured in the wrong place (must be under `channels.discord.guilds` or channel entry)
> * sender blocked by guild/channel `users` allowlist

> [accordion] Long-running handlers time out or duplicate replies
>
> Typical logs:
>
> * `Listener DiscordMessageListener timed out after 30000ms for event MESSAGE_CREATE`
> * `Slow listener detected ...`
>
> Canonical knob:
>
> * single-account: `channels.discord.eventQueue.listenerTimeout`
> * multi-account: `channels.discord.accounts.<accountId>.eventQueue.listenerTimeout`
>
> Additional event queue tuning:
>
> * `channels.discord.eventQueue.maxQueueSize` — max events queued before backpressure (default: 10000)
> * `channels.discord.eventQueue.maxConcurrency` — max concurrent event processing operations (default: 50)
>
> Recommended baseline:
>
> ```json5 theme={"dark"}
> {
>   channels: {
>     discord: {
>       accounts: {
>         default: {
>           eventQueue: {
>             listenerTimeout: 120000,
>           },
>         },
>       },
>     },
>   },
> }
> ```
>
> Tune this first before adding alternate timeout controls elsewhere.

> [accordion] Permissions audit mismatches
>
> `channels status --probe` permission checks only work for numeric channel IDs.
>
> If you use slug keys, runtime matching can still work, but probe cannot fully verify permissions.

> [accordion] DM and pairing issues
>
> * DM disabled: `channels.discord.dm.enabled=false`
> * DM policy disabled: `channels.discord.dmPolicy="disabled"` (legacy: `channels.discord.dm.policy`)
> * awaiting pairing approval in `pairing` mode

> [accordion] Bot to bot loops
>
> By default bot-authored messages are ignored.
>
> If you set `channels.discord.allowBots=true`, use strict mention and allowlist rules to avoid loop behavior.

> [accordion] Voice STT drops with DecryptionFailed(...)
>
> * keep WednesdayAI current (`wednesdayai update`) so the Discord voice receive recovery logic is present
> * confirm `channels.discord.voice.daveEncryption=true` (default)
> * start from `channels.discord.voice.decryptionFailureTolerance=24` (upstream default) and tune only if needed
> * watch logs for:
>   * `discord voice: DAVE decrypt failures detected`
>   * `discord voice: repeated decrypt failures; attempting rejoin`
> * if failures continue after automatic rejoin, collect logs and compare against [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419)

## Configuration reference pointers

Primary reference:

* [Configuration reference - Discord](https://docs.wednesdayai.dev/next/admin/gateway/configuration-reference.md#discord)

High-signal Discord fields:

* startup/auth: `enabled`, `token`, `accounts.*`, `allowBots`
* policy: `groupPolicy`, `dm.*`, `guilds.*`, `guilds.*.channels.*`
* command: `commands.native`, `commands.useAccessGroups`, `configWrites`, `slashCommand.*`
* event queue: `eventQueue.listenerTimeout`, `eventQueue.maxQueueSize`, `eventQueue.maxConcurrency`
* reply/history: `replyToMode`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
* delivery: `textChunkLimit`, `chunkMode` (`length` | `newline` | `paragraph`), `chunkNewlinePacking` (deprecated), `maxLinesPerMessage`
* streaming: `streaming` (legacy alias: `streamMode`), `draftChunk`, `blockStreaming`, `blockStreamingCoalesce`
* media/retry: `mediaMaxMb`, `retry`
* actions: `actions.*`
* presence: `activity`, `status`, `activityType`, `activityUrl`
* UI: `ui.components.accentColor`
* intents: `intents.presence`, `intents.guildMembers`
* features: `pluralkit`, `execApprovals`, `intents`, `agentComponents`, `heartbeat`, `responsePrefix`, `ackReaction`, `ackReactionScope`, `proxy`, `guilds.*.reactionNotifications`

**Inbox ingestion:** Discord channel config alone never ingests Discord messages into the
inbox. An account becomes an inbox source with `mode: "inbox"` (see
[Account mode](https://docs.wednesdayai.dev/next/admin/channels/channel-routing.md#account-mode)); a personal account next to the bot
account in channel mode is the typical shape:

```json5 theme={"dark"}
{
  channels: {
    discord: {
      accounts: {
        default: { token: "${DISCORD_BOT_TOKEN}" }, // bot, channel mode
        personal: { mode: "inbox" }, // personal, inbox only
      },
    },
  },
}
```

An inbox-mode account never chats: no agent replies, no pairing, no allowlist gating, and no
automatic read receipts. It feeds the inbox through the history scanner (60 s REST polling)
only, and the scanner walks guild channels — Discord DMs are not ingested. Existing inbox
rows are never removed when the account leaves inbox mode or is removed from config.

## Safety and operations

* Treat bot tokens as secrets (`DISCORD_BOT_TOKEN` preferred in supervised environments).
* Grant least-privilege Discord permissions.
* If command deploy/state is stale, restart gateway and re-check with `wednesdayai channels status --probe`.

## Related

* [Pairing](https://docs.wednesdayai.dev/next/admin/channels/pairing.md)
* [Channel routing](https://docs.wednesdayai.dev/next/admin/channels/channel-routing.md)
* [Multi-agent routing](https://docs.wednesdayai.dev/next/developers/concepts/multi-agent.md)
* [Troubleshooting](https://docs.wednesdayai.dev/next/admin/channels/troubleshooting.md)
* [Slash commands](https://docs.wednesdayai.dev/next/users/tools/slash-commands.md)


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