# Discord

> Connect Discord to your agents for messaging, events, and bot interactions.

**URL:** https://inference.sh/docs/credentials/discord
**Last updated:** 2026-09-24

---

Connect Discord to your agents for messaging, events, and bot interactions.

---

## Overview

Discord credentials let your agents send messages, respond to events, and interact with Discord servers through your own bot.

### Why "Bring Your Own Key" (BYOK)?

By creating your own Discord application and bot, you get complete control over which servers receive your bot and what events it can respond to.

**Benefits:**

- **Your own bot** — customize the name, avatar, and permissions
- **Isolated events** — only receive events from servers where your bot is invited
- **Full control** — configure exactly which intents and events to use
- **Webhook verification** — secure interactions with your public key

---

## Prerequisites

Before connecting, you'll need:

1. A Discord account
2. A Discord server where you have admin permissions (to invite your bot)

---

## Step 1: Create a Discord Application

1. Go to the [Discord Developer Portal](https://discord.com/developers/applications)
2. Click **New Application**
3. Name your application (e.g., "Inference Agent")
4. Agree to the Terms of Service
5. Click **Create**

---

## Step 2: Create a Bot

1. In your application, go to the **Bot** section
2. Click **Add Bot**
3. Customize your bot:
   - **Username** — the name shown in servers
   - **Icon** — your bot's avatar
4. Under **Privileged Gateway Intents**, enable what you need:

| Intent | Allows |
|--------|--------|
| **Presence Intent** | See user online/offline status |
| **Server Members Intent** | See member join/leave events |
| **Message Content Intent** | Read message text (required for most bots) |

5. Copy the **Token** — you'll need this

> **Important:** Never share your bot token. If compromised, regenerate it immediately.

---

## Step 3: Configure OAuth2

1. Go to the **OAuth2** section
2. Copy the **Client ID** and **Client Secret**
3. Add a redirect URL:

| Environment | Callback URL |
|-------------|-------------|
| Production | `https://app.inference.sh/settings/secrets/oauth/discord` |
| Staging | `https://app.staging.inference.sh/settings/secrets/oauth/discord` |
| Local dev | `http://localhost:3000/settings/secrets/oauth/discord` |

4. Under **OAuth2 URL Generator**, select scopes:
   - `identify` — access user info
   - `email` — access user email
   - `guilds` — see user's servers
   - `bot` — add bot to servers

---

## Step 4: Get Your Credentials

From your Discord application, collect:

| Credential | Location | Purpose |
|------------|----------|---------|
| **Application ID** | General Information | OAuth authentication |
| **Client Secret** | OAuth2 | OAuth authentication |
| **Bot Token** | Bot | Send messages, receive events |
| **Public Key** | General Information | Verify interaction webhooks |

---

## Step 5: Connect in inference shell

### Configure credentials

1. Go to **vaults → credentials**
2. Find **Discord** and click **Configure**
3. Enter your credentials:
   - **Application ID** (Client ID)
   - **Client Secret**
   - **Bot Token**
   - **Public Key** (for webhook verification)
4. Click **Save credentials**

> These are stored securely as encrypted secrets.

### Authorize the connection

1. Click **Connect**
2. You'll be redirected to Discord to authorize
3. Select which server to add the bot to
4. Review bot permissions
5. Click **Authorize**
6. Done! Your Discord credential is now active.

---

## Inviting Your Bot to Servers

To use your bot in a server, it needs to be invited with the right permissions:

1. Go to **OAuth2 → URL Generator** in the Developer Portal
2. Select scopes: `bot`, `applications.commands`
3. Select bot permissions based on your needs:

| Permission | Allows |
|------------|--------|
| Read Messages/View Channels | See channels and messages |
| Send Messages | Post messages |
| Manage Messages | Delete/pin messages |
| Read Message History | Access older messages |
| Add Reactions | React to messages |
| Use Slash Commands | Respond to `/commands` |

4. Copy the generated URL and open it
5. Select a server and authorize

---

## Agent chat and event triggers

**Agent messaging channel webhooks** (per-agent chat endpoints like Slack's) are not available for Discord yet. Only Slack is registered for `POST /agents/{id}/channel/{provider}` today. See [Slack](/docs/credentials/slack#event-subscriptions-agent-chat) for the supported setup.

Discord **event triggers** (for example `discord.message.created`, `discord.member.joined`) are available after you connect via OAuth. Subscribe to them on an agent in the web app. No global webhook URL is required.

Do **not** point Discord's Interactions Endpoint URL at `https://api.inference.sh/webhooks/discord` — that path is not implemented. Slash commands and button interactions must be hosted on your own infrastructure for now.

---

## Capabilities

| Capability | Description | Required Scopes |
|------------|-------------|-----------------|
| `discord.identify` | Access user info | `identify` |
| `discord.email` | Access user email | `identify`, `email` |
| `discord.guilds` | List user's servers | `guilds` |
| `discord.guilds.members.read` | Read server members | `guilds.members.read` |
| `discord.messages.read` | Read messages | `messages.read` |
| `discord.bot` | Add bot to servers | `bot` |

---

## Using in apps

Declare Discord requirements in your app:

```yaml
# inf.yml
credentials:
  - key: discord.bot
    description: Send messages to Discord

  - key: discord.guilds
    description: List available servers
    optional: true
```

At runtime, your app receives:

```bash
DISCORD_ACCESS_TOKEN=oauth2-user-token
DISCORD_BOT_TOKEN=bot-token
DISCORD_USER_ID=123456789
```

### Example: Send a message

```python
import discord
import os

client = discord.Client(intents=discord.Intents.default())

@client.event
async def on_ready():
    channel = client.get_channel(CHANNEL_ID)
    await channel.send("Hello from my AI agent! 🤖")
    await client.close()

client.run(os.environ["DISCORD_BOT_TOKEN"])
```

### Example: Using webhooks (simpler)

```python
import requests
import os

webhook_url = "https://discord.com/api/webhooks/..."

requests.post(webhook_url, json={
    "content": "Hello from my AI agent! 🤖"
})
```

### Example: REST API

```python
import requests
import os

headers = {
    "Authorization": f"Bot {os.environ['DISCORD_BOT_TOKEN']}"
}

# Send a message
response = requests.post(
    f"https://discord.com/api/v10/channels/{channel_id}/messages",
    headers=headers,
    json={"content": "Hello!"}
)
```

---

## Gateway Events (Real-time)

For real-time events, your bot connects to Discord's Gateway:

| Event | Trigger |
|-------|---------|
| `MESSAGE_CREATE` | New message posted |
| `MESSAGE_REACTION_ADD` | Reaction added |
| `GUILD_MEMBER_ADD` | User joined server |
| `GUILD_MEMBER_REMOVE` | User left server |
| `INTERACTION_CREATE` | Slash command or button click |

> Note: Gateway connections require a persistent process. For simpler use cases, consider using webhooks or the REST API.

---

## Security

- **Your bot** — you control the application and its permissions
- **Public key verification** — interactions are cryptographically verified
- **Bot token** — keep this secret; regenerate if compromised
- **Permission scopes** — bots only get permissions you explicitly grant

### Revoking access

1. **From inference shell**: **vaults → credentials → disconnect**
2. **From Discord**: Server Settings → Integrations → Remove bot
3. **Regenerate token**: Developer Portal → Bot → Reset Token

---

## Troubleshooting

### "Invalid token"

- Verify your bot token is correct
- Check if the token was regenerated
- Ensure no extra spaces in the token

### "Missing permissions"

- The bot needs specific permissions for each action
- Re-invite the bot with the required permissions
- Check Server Settings → Roles for the bot's role

### "Missing access"

- Your bot isn't in the server, or lacks channel access
- Invite the bot or check channel permissions

### "Interaction failed"

- Verify your Public Key in inference shell matches Discord
- Check that the Interactions Endpoint URL is correct

### "Message content intent required"

- Enable **Message Content Intent** in Bot settings
- This is required to read message text

---

## Rate Limits

Discord has rate limits to prevent abuse:

| Action | Limit |
|--------|-------|
| Messages per channel | 5/5s |
| Global requests | 50/s |
| Gateway connections | 1/5s |

The Discord libraries handle rate limiting automatically.

---

## Next

→ [Back to Credentials Overview](/docs/credentials/overview)