# Discord

> Set up an Aerostack bot on Discord — create a Discord application, configure interactions endpoint, and register slash commands.

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.

Aerostack Discord bots use **slash command interactions only**, not message events. This means the bot responds when users type `/ask` — it does not read or respond to regular chat 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

1. Go to the [Discord Developer Portal](https://discord.com/developers/applications)
2. Click **New Application** and give it a name
3. Navigate to the **General Information** tab and copy the **Application ID** and **Public Key**
4. 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

Keep your bot token and public key secret. Store them securely and never commit them to source control.

---

## Step 2: Invite the Bot to Your Server

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

---

## Step 3: Configure in Aerostack

### Via Dashboard

1. Navigate to **Bots** in the sidebar
2. Click on your bot (or create a new one with platform set to **Discord**)
3. 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

```bash
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:
1. Sets the **Interactions Endpoint URL** on your Discord application

2. **Registers slash commands** (`/ask` and `/reset`)

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

Response:

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

Discord requires a response within 3 seconds of receiving an interaction. Aerostack handles this by immediately returning a "deferred" response (type 5), then processing the message and sending a follow-up message asynchronously.

---

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