---
name: discord-bot-api
description: Discord Bot API via curl. Use this skill to interact with channels, guilds, users, messages, roles, and webhooks using a bot token.
---

# Discord Bot API

Use the Discord Bot API via direct curl calls to manage channels, guilds, messages, roles, and users.

Official docs: https://discord.com/developers/docs

## When to Use

Use this skill when you need to:

- Send messages to specific channels
- Read messages from channels
- Manage channels (create, edit, delete)
- Get server info (guilds, members, roles)
- React to messages and moderate content
- Create webhooks programmatically

## Prerequisites

### 1. Create Application

1. Go to Discord Developer Portal
2. Click "New Application" and give it a name
3. Go to "Bot" section and click "Add Bot"

### 2. Get Bot Token

1. In Bot section, click "Reset Token"
2. Copy the token (shown only once)

```bash
export DISCORD_BOT_TOKEN="MTIzNDU2Nzg5MDEyMzQ1Njc4OQ.ABcDeF.xxxxx..."
```

### 3. Enable Intents (if needed)

In Bot section, enable:
- Presence Intent (for user status)
- Server Members Intent (for member list)
- Message Content Intent (for reading messages)

### 4. Invite Bot to Server

1. Go to OAuth2 → URL Generator
2. Select scopes: bot, applications.commands
3. Select permissions needed (e.g., Send Messages, Read Messages)
4. Copy URL and open in browser to invite

### 5. Get IDs

Enable Developer Mode: User Settings → Advanced → Developer Mode
Right-click any channel/user/server → Copy ID

## API Commands

Base URL: `https://discord.com/api/v10`
Authorization header: `Authorization: Bot YOUR_TOKEN`

### Get Current Bot User
```bash
curl -s "https://discord.com/api/v10/users/@me" \
  -H "Authorization: Bot ${DISCORD_BOT_TOKEN}" | jq '{id, username, discriminator}'
```

### Send Message to Channel
```bash
curl -s -X POST "https://discord.com/api/v10/channels/{CHANNEL_ID}/messages" \
  -H "Authorization: Bot ${DISCORD_BOT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello from bot!"}'
```

### Send Embed Message
```bash
curl -s -X POST "https://discord.com/api/v10/channels/{CHANNEL_ID}/messages" \
  -H "Authorization: Bot ${DISCORD_BOT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "embeds": [{
      "title": "Bot Message",
      "description": "This is from the bot API",
      "color": 5793266
    }]
  }'
```

### Get Channel Info
```bash
curl -s "https://discord.com/api/v10/channels/{CHANNEL_ID}" \
  -H "Authorization: Bot ${DISCORD_BOT_TOKEN}" | jq '{id, name, type, guild_id}'
```

### Get Channel Messages
```bash
curl -s "https://discord.com/api/v10/channels/{CHANNEL_ID}/messages?limit=10" \
  -H "Authorization: Bot ${DISCORD_BOT_TOKEN}" | jq '.[] | {id, author: .author.username, content}'
```

### Delete Message
```bash
curl -s -X DELETE "https://discord.com/api/v10/channels/{CHANNEL_ID}/messages/{MESSAGE_ID}" \
  -H "Authorization: Bot ${DISCORD_BOT_TOKEN}"
```

### Add Reaction
```bash
curl -s -X PUT "https://discord.com/api/v10/channels/{CHANNEL_ID}/messages/{MESSAGE_ID}/reactions/%F0%9F%91%8D/@me" \
  -H "Authorization: Bot ${DISCORD_BOT_TOKEN}" \
  -H "Content-Length: 0"
```

Note: Emoji must be URL encoded (👍 = %F0%9F%91%8D)

### Get Guild (Server) Info
```bash
curl -s "https://discord.com/api/v10/guilds/{GUILD_ID}" \
  -H "Authorization: Bot ${DISCORD_BOT_TOKEN}" | jq '{id, name, member_count, owner_id}'
```

### List Guild Channels
```bash
curl -s "https://discord.com/api/v10/guilds/{GUILD_ID}/channels" \
  -H "Authorization: Bot ${DISCORD_BOT_TOKEN}" | jq '.[] | {id, name, type}'
```

### Get Guild Members
```bash
curl -s "https://discord.com/api/v10/guilds/{GUILD_ID}/members?limit=10" \
  -H "Authorization: Bot ${DISCORD_BOT_TOKEN}" | jq '.[] | {user: .user.username, nick, joined_at}'
```

### Get Guild Roles
```bash
curl -s "https://discord.com/api/v10/guilds/{GUILD_ID}/roles" \
  -H "Authorization: Bot ${DISCORD_BOT_TOKEN}" | jq '.[] | {id, name, color, position}'
```

### Create Webhook
```bash
curl -s -X POST "https://discord.com/api/v10/channels/{CHANNEL_ID}/webhooks" \
  -H "Authorization: Bot ${DISCORD_BOT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Webhook"}' | jq '{id, token}'
```

### Create Text Channel
```bash
curl -s -X POST "https://discord.com/api/v10/guilds/{GUILD_ID}/channels" \
  -H "Authorization: Bot ${DISCORD_BOT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"name": "new-channel", "type": 0}' | jq '{id, name}'
```

## Channel Types

| Type | Description |
|------|-------------|
| 0 | Text channel |
| 2 | Voice channel |
| 4 | Category |
| 5 | Announcement |
| 13 | Stage |
| 15 | Forum |

## Guidelines

- **Rate limits**: Check X-RateLimit-* headers; implement backoff
- **Token security**: Never expose bot tokens
- **Permissions**: Bot needs appropriate permissions for each action
- **Intents**: Enable required intents in Developer Portal
- **API version**: Use /v10 for latest stable API
