# Discourse AI: Discord Bot Integration Guide

**URL:** https://meta.discourse.org/t/discourse-ai-discord-bot-integration-guide/390391
**Category:** Sysadmins
**Created:** [December 4, 2025, 10:07am UTC](https://meta.discourse.org/t/discourse-ai-discord-bot-integration-guide/390391 "2025-12-04T10:07:23Z")
**Posts on this page:** 1
**Page:** 1

<div class="post-metadata">

### Author: ![DevTeVe](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/devteve/32/487601_2.png) [@DevTeVe](https://meta.discourse.org/u/DevTeVe)
#### Post date: [December 4, 2025, 10:07am UTC](https://meta.discourse.org/t/discourse-ai-discord-bot-integration-guide/390391/1 "2025-12-04T10:07:23Z")

</div>

> **Disclaimer:**  
> I am not the creator of the integration, I can’t provide support for it beyond a best-effort friendly community help, I am just another user that wanted this setup on their site and didn’t find a clear way to do so, and while doing so I found a bug, which is why I made a PR to fix it, but my knowledge on this is rather minimal.

# How it Works (Architecture)

Before setting this up, it is important to understand that **you do not need to host a separate bot application** or run a “bot” script (like a Node.js or Python bot) on your server.

> **This integration uses Discord Interactions (Webhooks) combined with Progressive Edits to simulate a streaming AI experience:**
>
> 1. **User Action:** A user types `/ask` in your Discord server.
> 2. **Webhook:** Discord sends an HTTP POST request directly to your Discourse server.
> 3. **Immediate Ack:** Discourse responds instantly with a “Searching…” status. This prevents the Discord “Interaction Failed” timeout.
> 4. **Streaming Response:** A background job starts generating the AI answer. As the AI produces text, Discourse sends frequent **HTTP PATCH** requests to _edit_ the Discord message in real-time.
> 
> _Result:_ Users see the answer typing out live, just like ChatGPT, rather than waiting for a single static block of text.
> 
> **Key Benefit:** Since Discourse handles the logic internally, there is no extra infrastructure to maintain. If your forum is online, your bot is online.

This guide details the complete process for integrating the Discourse AI bot with a Discord server. It includes specific instructions for **manually registering slash commands via the API** , which is currently required to bypass automatic synchronization issues in the plugin.

## Prerequisites

- **Discourse Admin Access:** You must be an administrator of your self-hosted Discourse instance.
- **Discord Admin Access:** You must have “Manage Server” permissions on the target Discord server.
- **[Discourse AI](https://meta.discourse.org/t/discourse-ai/259214)**: Enabled on your Discourse server
- **Terminal Access:** You will need a terminal to run `curl` commands.

## 1. Create the Discord Application

1. Navigate to the [Discord Developer Portal](https://discord.com/developers/applications).
2. Click **New Application** in the top right corner.
3. Give your application a name (e.g., “Discourse Helper”) and click **Create**.
4. **Copy Credentials:** On the **General Information** page, locate and save the following for later:

 ![image](https://global.discourse-cdn.com/meta/original/4X/4/8/1/481cdd154f62f2998b6f48618d71c6e0d1b1d002.png)

## 2. Configure the Bot User

1. In the left sidebar menu, click **Bot**.

2. Click **Reset Token**.

3. **Enable Privileged Intents:**

4. Click **Save Changes**.

 ![image](https://global.discourse-cdn.com/meta/original/4X/6/0/5/605cd9175cdcb14d1ce5d5d0bf533af4346a8967.jpeg)

# 3. Configure Discourse Settings

1. Log in to your Discourse Admin Panel.

2. Navigate to **Admin** → **Plugins** → **AI** → **Features**.

3. Search for “discord” and click on edit:  

4. Fill in the details

5. **Allow your Discord Server:**

# 4. Set the Interactions Endpoint

1. Construct your endpoint URL: `=ForumUrl=/discourse-ai/discord/interactions`
2. Return to the [Discord Developer Portal](https://discord.com/developers/applications).
3. On the **General Information** page, scroll to **Interactions Endpoint URL**.
4. Paste your URL and click **Save Changes**.
  - _ **Success** :_ Discord will send a test signal. If it saves without error, your Discourse instance successfully verified the signature.
  - _ **Failure** :_ If you get an error, ensure `AI Discord app ID` and `AI Discord app public key` are saved correctly in Discourse Settings.

# 5. Invite the Bot

1. In the Developer Portal, click **Installation** in the sidebar.
2. **Scopes:** Check the boxes for `bot` and `applications.commands`.
3. **Bot Permissions:** Check the following:
  - Send Messages
  - Embed Links
  - Attach Files
  - Read Message History

4. Copy the **Installation Link** at the top of the page.
5. Open this URL in a browser tab and authorize the bot to join your server.

 ![image](https://global.discourse-cdn.com/meta/original/4X/4/7/6/4769726da3ce0028f87a28d7eb036eead111a0cc.png)

# 6. Register the Slash Command (Manual API Call)

**Important:** The command parameter name MUST be `query`.

## For Mac / Linux (Bash)

```plaintext
curl -X POST "https://discord.com/api/v10/applications/=ApplicationId=/commands" \
  -H "Authorization: Bot =BotToken=" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ask",
    "description": "Ask the AI a question",
    "options": [
        {
            "name": "query",
            "description": "What is your question?",
            "type": 3,
            "required": true
        }
    ]
}'

```

- **Success Response:** You should receive a JSON response containing the new command’s ID.
- **Error 401?** Ensure you kept the word `Bot ` (with a space) before your token in the Authorization header.

# 7. Verification

1. Open your Discord Server.
2. Type `/ask` in a text channel.
3. The command menu should appear. Select `/ask` and type a question in the `query` field.
4. **Expected Behavior:**
  - **Immediate:** Bot replies “Searching…”
  - **After a few seconds:** The message updates with the AI’s answer.

# Troubleshooting

| Error | Cause | Solution |
| --- | --- | --- |
| **401 Unauthorized** (in Curl) | Bad Token format | Ensure header is `Authorization: Bot =BotToken=`. Use the token from the **Bot** tab, not the General tab. |
| **Job** Exception: context **must be an instance of BotContext** | Wrong Payload | Make sure you are up to date, this was fixed on [FIX: Discord Bot crash due to missing BotContext in PersonaReplier by devtekve · Pull Request #36429 · discourse/discourse · GitHub](https://github.com/discourse/discourse/pull/36429#issuecomment-3610843271) |