Skip to content
herdctl herdctl

Discord Chat Quick Start

Get your herdctl agent chatting on Discord in under 5 minutes. This guide covers the minimal setup—see the full Discord reference for advanced configuration.

1. Create a Discord Bot

Section titled “1. Create a Discord Bot”
  1. Go to Discord Developer Portal
  2. Click New Application and give it a name
  3. Go to Bot → click Reset Token → copy the token

2. Enable Message Content Intent

Section titled “2. Enable Message Content Intent”

Still in the Developer Portal:

  1. Go to Bot → scroll to Privileged Gateway Intents
  2. Enable Message Content Intent
  3. Click Save Changes

3. Invite the Bot

Section titled “3. Invite the Bot”
  1. Go to OAuth2 → URL Generator
  2. Select scopes: bot, applications.commands
  3. Select permissions: Send Messages, Read Message History, Use Slash Commands
  4. Copy the URL and open it to invite the bot to your server

4. Get Your Discord IDs

Section titled “4. Get Your Discord IDs”

Enable Developer Mode in Discord (User Settings → Advanced → Developer Mode), then:

  • Guild ID: Right-click server icon → Copy Server ID
  • Channel ID: Right-click channel → Copy Channel ID

5. Set Environment Variables

Section titled “5. Set Environment Variables”
Terminal window
export DISCORD_BOT_TOKEN="your-bot-token-here"
export DISCORD_GUILD_ID="123456789012345678"
export DISCORD_CHANNEL_ID="987654321098765432"

6. Add Chat Config to Agent

Section titled “6. Add Chat Config to Agent”

Add the chat.discord section to your agent YAML:

name: my-agent
description: "Agent with Discord chat"


system_prompt: |
  You are a helpful assistant. Answer questions clearly and concisely.


chat:
  discord:
    bot_token_env: DISCORD_BOT_TOKEN
    guilds:
      - id: "${DISCORD_GUILD_ID}"
        channels:
          - id: "${DISCORD_CHANNEL_ID}"
            mode: mention  # Respond when @mentioned
    dm:
      enabled: true
      mode: auto  # Always respond to DMs

7. Start and Test

Section titled “7. Start and Test”
Terminal window
herdctl start

You should see:

[my-agent] Connecting to Discord...
[my-agent] Connected to Discord: MyBot#1234

Now try it:

  • In the channel: @MyBot Hello!
  • In a DM: Just say Hello!

Slash Commands

Section titled “Slash Commands”

Your bot automatically supports:

CommandDescription
/helpShow available commands
/resetClear conversation context
/statusShow bot connection info

Next Steps

Section titled “Next Steps”