Discourse AI: Discord Bot Integration Guide

[DevTeVe (DevTek Ve)]

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: 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.
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:

2. Configure the Bot User

1. In the left sidebar menu, click Bot.

2. Click Reset Token.

3. Enable Privileged Intents:

   • Scroll down to the “Privileged Gateway Intents” section.
   • Toggle Message Content Intent to ON. (This allows the bot to read the messages it needs to reply to).

4. Click Save Changes.

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

   • AI Discord app ID: Paste =ApplicationId=
   • AI Discord app public key: Paste =PublicKey=
     
     

5. Allow your Discord Server:

   • Open your Discord app and enable Developer Mode (User Settings → Advanced → Developer Mode).
   • Right-click your server icon in the sidebar and select Copy Server ID.
   • In Discourse Settings, paste this ID into the AI Discord allowed guilds field.

4. Set the Interactions Endpoint

1. Construct your endpoint URL: =ForumUrl=/discourse-ai/discord/interactions
2. Return to the Discord Developer Portal.
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.

6. Register the Slash Command (Manual API Call)

Important: The command parameter name MUST be query.

For Mac / Linux (Bash)

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