Discord

Connect your Aerostack bot to Discord via the Interactions API. Users interact with your bot through slash commands (/ask and /reset), and responses are delivered as follow-up messages.

Prerequisites

An Aerostack account with an existing bot (or create one during setup)
A Discord account with permission to create applications

Step 1: Create a Discord Application

Go to the Discord Developer Portal
Click New Application and give it a name
Navigate to the General Information tab and copy the Application ID and Public Key
Navigate to the Bot tab:
- Click Add Bot (if not already created)
- Copy the Bot Token (click “Reset Token” if needed)
- Under Privileged Gateway Intents, no special intents are required for slash commands

Step 2: Invite the Bot to Your Server

Navigate to the OAuth2 tab in the Developer Portal
Under OAuth2 URL Generator, select the scopes: bot, applications.commands
Under Bot Permissions, select: Send Messages, Use Slash Commands
Copy the generated URL and open it in your browser
Select the server you want to add the bot to and authorize

Step 3: Configure in Aerostack

Via Dashboard

Navigate to Bots in the sidebar
Click on your bot (or create a new one with platform set to Discord)
In the Platform Configuration section, enter:
- Application ID — from the General Information tab
- Public Key — from the General Information tab
- Bot Token — from the Bot tab

Via API

curl -X POST https://api.aerostack.dev/api/bots \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Discord Support Bot",
    "platform": "discord",
    "workspace_id": "YOUR_WORKSPACE_ID",
    "system_prompt": "You are a helpful assistant in a Discord server.",
    "platform_config": {
      "application_id": "1234567890123456789",
      "public_key": "abc123def456...",
      "bot_token": "MTIz...abc"
    }
  }'

Step 4: Activate

Activating does two things:

Sets the Interactions Endpoint URL on your Discord application

Registers slash commands (/ask and /reset)

curl -X POST https://api.aerostack.dev/api/bots/YOUR_BOT_ID/activate \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

{
  "status": "active",
  "webhook_url": "https://api.aerostack.dev/api/bots/webhook/discord/bt_a1b2c3d4e5f6g7h8i9j0"
}

Step 5: Test

In your Discord server, type /ask followed by your message:

/ask message: What are your business hours?

The bot will show “thinking…” briefly, then respond with the answer.

Use /reset to clear the conversation history and start fresh.

Platform Config Fields

Field	Required	Description
`application_id`	Yes	Discord application ID
`public_key`	Yes	Discord application public key (used for Ed25519 signature verification)
`bot_token`	Yes	Discord bot token
`guild_ids`	No	Array of guild (server) IDs for guild-scoped slash commands. If omitted, commands are registered globally.
`respond_to_mentions`	No	Reserved for future use
`respond_to_dms`	No	Reserved for future use

Slash Commands

Aerostack automatically registers two slash commands when a bot is activated:

Command	Description
`/ask`	Send a message to the bot. Has a required `message` option.
`/reset`	Clear the conversation history and start a new conversation.

Guild vs Global Commands

If guild_ids is provided, commands are registered only to the first guild in the array. This is faster (commands appear instantly).
If guild_ids is omitted, commands are registered globally. Global commands can take up to 1 hour to propagate across all servers.

Webhook Verification

Discord uses Ed25519 signature verification for all interactions. The public_key from your Discord application is used to verify every incoming request. This verification is mandatory — Discord will not send interactions to an endpoint that fails the verification ping.

Unlike other platforms, you cannot skip signature verification for Discord.

Message Limits

Discord enforces a 2000 character limit per message. If the bot’s response exceeds this, Aerostack automatically splits it into multiple follow-up messages at whitespace boundaries.

Rate Limits

Discord webhooks are rate-limited at 120 requests per minute per bot (higher than other platforms due to the interaction model).

Troubleshooting

Issue	Solution
Slash commands not appearing	Wait up to 1 hour for global commands. For instant registration, use `guild_ids` in your platform config.
”Interaction failed” error in Discord	Check that your bot is activated and the interactions endpoint URL is set correctly in the Discord Developer Portal.
Bot responds with “Application did not respond”	The bot engine may be timing out. Check your `timeout_ms` setting (default 30s, max 60s).
Ed25519 verification failing	Verify that your `public_key` matches the one in the Discord Developer Portal.