Agent MessengerAgent Messenger
Platform Guides

Discord Bot

Complete reference for the agent-discordbot CLI.

Tip: agent-discordbot uses bot tokens instead of user tokens. Ideal for server-side and CI/CD integrations.

Quick Start

# 1. Set your bot token (from Discord Developer Portal)
agent-discordbot auth set your-bot-token

# 2. Verify authentication
agent-discordbot auth status

# 3. Send a message
agent-discordbot message send general "Hello from bot!"

Authentication

Create a Discord Bot

  1. Go to discord.com/developers/applications and click New Application
  2. Give it a name and click Create
  3. Go to Bot in the left sidebar
  4. Click Reset Token (or Copy if the token is still visible)
  5. Copy the token and store it securely

Invite the Bot to a Server

Use this URL format, replacing YOUR_CLIENT_ID with your application's client ID (found on the General Information page):

https://discord.com/api/oauth2/authorize?client_id=YOUR_CLIENT_ID&permissions=274877975552&scope=bot

Or generate a URL manually:

  1. Go to OAuth2 > URL Generator in the left sidebar
  2. Under Scopes, select bot
  3. Under Bot Permissions, select the permissions your bot needs
  4. Copy the generated URL and open it in your browser
  5. Select the server and authorize

Message Content Privileged Intent

For servers (guilds) with 100 or more members, the Message Content intent must be enabled:

  1. Go to discord.com/developers/applications
  2. Select your application
  3. Go to Bot in the left sidebar
  4. Under Privileged Gateway Intents, enable Message Content Intent
  5. Save changes

Without this, the bot won't receive message content in large servers.

Authentication Commands

# Set bot token (validates against Discord API before saving)
agent-discordbot auth set <token>

# Set with a custom bot identifier for multi-bot setups
agent-discordbot auth set <token> --bot deploy

# Check bot auth status
agent-discordbot auth status

# Clear all stored credentials
agent-discordbot auth clear

# List stored bots
agent-discordbot auth list

# Switch active bot
agent-discordbot auth use <bot-id>

# Remove a stored bot
agent-discordbot auth remove <bot-id>

Multi-Bot Support

Store multiple bot tokens and switch between them:

# Add multiple bots
agent-discordbot auth set deploy-bot-token --bot deploy
agent-discordbot auth set alert-bot-token --bot alert

# List all stored bots
agent-discordbot auth list

# Switch active bot
agent-discordbot auth use deploy

# Use a specific bot for one command (without switching)
agent-discordbot message send general "Alert!" --bot alert

# Remove a stored bot
agent-discordbot auth remove deploy

Permissions Reference

PermissionUsed For
Send MessagesSending messages to channels
Send Messages in ThreadsPosting into threads with --thread (message send, file upload)
Read Message HistoryReading past messages, replying with --reply, and thread list --archived
View ChannelsListing and accessing channels
Add ReactionsAdding and removing emoji reactions
Attach FilesUploading files to channels and threads
Manage ThreadsCreating and archiving threads

Environment Variables (CI/CD)

export E2E_DISCORDBOT_TOKEN=your-bot-token
export E2E_DISCORDBOT_SERVER_ID=1234567890123456789
export E2E_DISCORDBOT_SERVER_NAME="My Server"

Commands

Whoami Command

# Show current authenticated bot
agent-discordbot whoami
agent-discordbot whoami --pretty
agent-discordbot whoami --bot <bot-id>

Server Commands

# List servers the bot is in
agent-discordbot server list

# Show current server
agent-discordbot server current

# Switch active server
agent-discordbot server switch <server-id>

# Get server info
agent-discordbot server info <server-id>

Message Commands

# Send a message
agent-discordbot message send <channel> <text>
agent-discordbot message send general "Hello world"

# Reply to a message
agent-discordbot message send general "On it!" --reply 9876543210987654321

# Send a message into a thread. --thread takes a thread ID or an active
# thread name in that channel. The message lands in the thread, so the
# response's channel_id is the thread ID, not the parent channel.
agent-discordbot thread list general                     # find the thread ID
agent-discordbot message send general "Hello" --thread 9876543210987654321
agent-discordbot message send general "Hello" --thread "Release notes"

# List messages
agent-discordbot message list <channel>
agent-discordbot message list general --limit 50

# Get a single message by ID
agent-discordbot message get <channel> <message-id>

# Get thread replies
agent-discordbot message replies <channel> <thread-id>
agent-discordbot message replies general 9876543210987654321 --limit 50

# Edit a message (bot's own messages only)
agent-discordbot message edit <channel> <message-id> <text>

# Delete a message (bot's own messages only)
agent-discordbot message delete <channel> <message-id> --force

Channel Commands

# List channels in current server
agent-discordbot channel list

# Get channel info
agent-discordbot channel info <channel>
agent-discordbot channel info general

User Commands

# List server members
agent-discordbot user list

# Get user info
agent-discordbot user info <user-id>

Reaction Commands

# Add reaction (use emoji name without colons)
agent-discordbot reaction add <channel> <message-id> <emoji>
agent-discordbot reaction add general 9876543210987654321 thumbsup

# Remove reaction
agent-discordbot reaction remove <channel> <message-id> <emoji>

# List reactions on a message (emoji, count, and whether the bot reacted)
agent-discordbot reaction list <channel> <message-id>

File Commands

# Upload one or more files (max 10) to a channel
agent-discordbot file upload <channel> <file-path...> [--text <text>] [--thread <id|name>] [--reply <message-id>] [--filename <name>]
agent-discordbot file upload general ./report.pdf
agent-discordbot file upload general ./report.pdf ./chart.png --text "Weekly numbers"

# Upload into a thread (same --thread rules as message send)
agent-discordbot file upload general ./log.txt --thread "Release notes"

# Upload as a reply to a message
agent-discordbot file upload general ./fix.patch --reply 9876543210987654321

# Override the filename (single file only)
agent-discordbot file upload general ./tmp/abc123.txt --filename notes.txt

# List files in channel (attachments of the latest 100 messages, one request)
agent-discordbot file list <channel>

# Get a single file by attachment ID (searches back through the latest 1,000 messages)
agent-discordbot file info <channel> <file-id>

file list reads a single page of channel history, so it stays fast on busy channels. file info pages further back with before cursors and stops at the first matching attachment; a file older than the latest 1,000 messages reports File not found.

The upload response includes message_id, channel_id (the thread ID when --thread is used), and a files array with each attachment's id, filename, size, and url. Discord enforces the per-file size limit; oversized uploads come back as an error instead of being rejected locally.

Thread Commands

# Create a thread from a message
agent-discordbot thread create <channel> <name>
agent-discordbot thread create general "Discussion" --auto-archive-duration 1440

# List active threads in the server, or only those under one channel
agent-discordbot thread list
agent-discordbot thread list <channel>

# List archived threads (a channel is required; returns up to 100 with has_more)
agent-discordbot thread list <channel> --archived

# Archive a thread
agent-discordbot thread archive <thread-id>

Snapshot Command

Get server overview for AI agents (brief by default):

# Brief snapshot (default) — fast, minimal API calls
agent-discordbot snapshot

# Full snapshot — includes messages and members (slow, large output)
agent-discordbot snapshot --full

# Filtered full snapshots
agent-discordbot snapshot --full --channels-only
agent-discordbot snapshot --full --users-only

# Limit messages per channel (only with --full)
agent-discordbot snapshot --full --limit 10

Default returns brief JSON with:

  • Server ID
  • Channels (id, name) — text channels only
  • Hint for next commands

With --full, returns comprehensive JSON with:

  • Server ID
  • Channels with messages (id, name, messages)
  • Use --full --channels-only for channel type info
  • Use --full --users-only for members (id, username, global_name)

Key Differences from agent-discord

Featureagent-discordagent-discordbot
Token typeUser tokenBot token
Token sourceAuto-extracted from desktop appManual from Developer Portal
Message searchYesNo
DM commandsYesNo
Mention/Friend/Note/ProfileYesNo
Thread managementYesYes (create, list, archive)
File uploadYesYes (multi-file, into threads, as replies)
ReactionsYesYes (add, remove, list)
Multi-bot supportN/AYes (--bot flag)
CI/CD friendlyRequires desktop appYes

Global Options

All commands support these options:

OptionDescription
--prettyHuman-readable output instead of JSON
--bot <id>Use a specific bot for this command
--server <id>Use a specific server for this command

AI Agent Integration

See skills/agent-discordbot/ for:

  • Complete skill documentation
  • Runnable templates
  • Common patterns for AI agents

On this page