Skip to content
herdctl herdctl

Slack Chat Quick Start

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

1. Create a Slack App

Section titled “1. Create a Slack App”
  1. Go to api.slack.com/apps
  2. Click Create New App > From scratch
  3. Name it (e.g., “HerdBot”) and select your workspace

2. Enable Socket Mode

Section titled “2. Enable Socket Mode”
  1. Go to Settings > Socket Mode > toggle it on
  2. Create an App-Level Token with connections:write scope
  3. Copy the token (starts with xapp-) — save it now, you can’t see it again

3. Add Bot Scopes

Section titled “3. Add Bot Scopes”

Go to OAuth & Permissions > Bot Token Scopes and add:

  • app_mentions:read
  • chat:write
  • channels:history
  • files:write
  • reactions:write

4. Subscribe to Events

Section titled “4. Subscribe to Events”

Go to Event Subscriptions > toggle Enable Events on > Subscribe to bot events:

  • app_mention
  • message.channels
  • message.im

Click Save Changes.

5. Install to Workspace

Section titled “5. Install to Workspace”
  1. Go to Install App > Install to Workspace > Authorize
  2. Copy the Bot User OAuth Token (starts with xoxb-)

6. Add Bot to a Channel

Section titled “6. Add Bot to a Channel”

In Slack, go to the channel you want and type @YourBotName — click Invite to Channel when prompted.

Then get the channel ID: right-click the channel name > View channel details > copy the ID at the bottom.

7. Set Environment Variables

Section titled “7. Set Environment Variables”
Terminal window
export SLACK_BOT_TOKEN="xoxb-your-bot-token-here"
export SLACK_APP_TOKEN="xapp-your-app-token-here"
export SLACK_CHANNEL_ID="C0123456789"

Or add them to a .env file next to your herdctl.yaml.

8. Add Chat Config to Agent

Section titled “8. Add Chat Config to Agent”

Add the chat.slack section to your agent YAML:

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


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


chat:
  slack:
    bot_token_env: SLACK_BOT_TOKEN
    app_token_env: SLACK_APP_TOKEN
    channels:
      - id: "${SLACK_CHANNEL_ID}"
        mode: mention  # Respond when @mentioned

9. Start and Test

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

You should see:

[slack] Connecting to Slack via Socket Mode...
[slack] Connected to Slack: HerdBot

Now try it — in the channel, type: @HerdBot Hello!

Commands

Section titled “Commands”

Your bot automatically supports prefix commands:

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

Optional: Enable Direct Messages

Section titled “Optional: Enable Direct Messages”

If you want users to DM the bot directly, you need a few extra scopes and a settings change.

Add DM Scopes

Section titled “Add DM Scopes”

Go back to OAuth & Permissions > Bot Token Scopes and add:

  • im:history
  • im:read
  • im:write

You may need to reinstall the app to your workspace after adding these scopes (Slack will prompt you if so).

Enable the Messages Tab

Section titled “Enable the Messages Tab”
  1. Go to your app’s settings at api.slack.com/apps and select your app
  2. Click App Home in the left sidebar
  3. Scroll down to the Show Tabs section
  4. Make sure the Messages Tab toggle is enabled
  5. Check the box labelled “Allow users to send Slash commands and messages from the Messages tab”

Without these settings, users won’t see a message input when they open a DM with your bot.

Next Steps

Section titled “Next Steps”