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

# Discord Integration

Add a HolyDocs bot to your Discord server for documentation help and notifications.

## Overview

The HolyDocs Discord bot brings your documentation into your Discord server. Community members can ask questions and receive AI-powered answers sourced from your docs, and you can receive deployment notifications in a designated channel.

## Setting Up

**Navigate to Integrations**

In your project dashboard, go to **Integrations > Discord**.
  **Add the Bot**

Click **Add to Discord**. This opens Discord's OAuth flow to authorize the bot in your server.
  **Select a Server**

Choose the Discord server where you want to install the bot and grant the required permissions.
  **Configure Channel**

Set the channel where the bot should post notifications. The bot responds to slash commands in any channel it has access to.

## Bot Commands

The Discord bot supports these interaction commands:

| Command | Description |
|---|---|
| `/docs search <query>` | Search your documentation and return relevant results |
| `/docs ask <question>` | Ask a question and get an AI-generated answer from your docs |
| `/docs link <page>` | Get a direct link to a documentation page |

### Example Usage

```
/docs ask How do I configure dark mode?
```

The bot responds with:

```
📖 Dark Mode Configuration

HolyDocs supports three appearance modes. Set the default in docs.json:

{
  "appearance": {
    "default": "system",
    "strict": false
  }
}

Set "strict": true to lock to a specific mode and hide the toggle.

📄 Read more: Dark Mode
   https://docs.holydocs.com/dark-mode
```

## Interaction Webhooks

The Discord bot uses interaction webhooks (stateless HTTP POST), not the Discord Gateway. This means:

- No persistent WebSocket connection required
- Each command is an independent HTTP request
- Responses are sent via interaction webhook callbacks
- The bot works within Cloudflare Worker execution limits

## Security

Discord interactions are verified using Ed25519 signature verification:

- Discord sends a signature in the `X-Signature-Ed25519` header
- The `X-Signature-Timestamp` header provides replay protection
- HolyDocs verifies the signature using `crypto.subtle` before processing any interaction

Discord bot routes skip the dashboard session authentication. Instead, they use Discord's Ed25519 signature verification — a different mechanism from Slack's HMAC-SHA256.

## Notifications

Configure which events trigger Discord notifications:

| Event | Notification |
|---|---|
| Deployment completed | Success message with deployment URL |
| Deployment failed | Error alert with failure reason |
| Agent job completed | Summary with suggestion count |

## Environment Variables

The Discord integration requires these environment variables (set via `wrangler secret put`):

| Variable | Description |
|---|---|
| `DISCORD_APPLICATION_ID` | Your Discord application ID |
| `DISCORD_PUBLIC_KEY` | Public key for signature verification |
| `DISCORD_BOT_TOKEN` | Bot token for sending messages |

## API Endpoints

- `POST /api/v1/discord/interactions` — Discord interaction webhook
- `GET /api/v1/discord/oauth` — OAuth callback for bot installation

## Disconnecting

To remove the Discord integration:

1. Go to **Integrations > Discord** in the dashboard
2. Click **Disconnect**
3. Optionally remove the bot from your Discord server settings