Slack Channel Setup

Connect your AI agent to Slack workspaces so users can interact with your agent directly through Slack channels or direct messages.

Overview

A Slack channel allows your agent to:

• Receive messages from users in Slack channels or direct messages

• Respond to messages in real-time

• Participate in threaded conversations

• Support both public channels and private direct messages

Prerequisites

Before you begin, you'll need:

1. A Slack workspace where you have administrative access or permission to create apps

2. A Slack App that you've created (or permission to create one)

3. A published agent in your Stage5 project that you want to connect to Slack

Step 1: Create a Slack App

1. Go to Slack API - Your Apps

2. Click "Create New App"

3. Choose "From scratch"

4. Give your app a name (e.g., "Customer Support Bot")

5. Select the Slack workspace where you want to use the bot

6. Click "Create App"

Step 2: Configure OAuth & Permissions

1. In your app settings, navigate to "OAuth & Permissions" in the left sidebar

2. Scroll down to "Scopes" → "Bot Token Scopes"

3. Add the following required permissions:

   • chat:write - Send messages as the bot

   • channels:history - Read messages in public channels

   • groups:history - Read messages in private channels

   • im:history - Read messages in direct messages

   • im:write - Send direct messages

   • mpim:history - Read messages in group direct messages

   • mpim:write - Send group direct messages

   • channels:join - Allow the bot to join public channels

   • users:read - View user information for message attribution

4. Scroll up and click "Install to Workspace" (or "Reinstall to Workspace" if updating permissions)

5. Authorize the app in your workspace

6. Copy the "Bot User OAuth Token" - you'll need this in the next step (it starts with xoxb-)

Step 3: Configure Event Subscriptions

1. In your app settings, navigate to "Event Subscriptions" in the left sidebar

2. Toggle "Enable Events" to ON

3. Set the "Request URL" - This will be provided by Stage5 after you publish your channel. For now, you can leave this blank and update it later, or use a placeholder URL temporarily.

4. In "Subscribe to bot events", add the following events:

   • message.channels - Receive messages posted in public channels

   • message.groups - Receive messages posted in private channels

   • message.im - Receive direct messages

   • message.mpim - Receive group direct messages

5. Click "Save Changes"

Step 4: Get Your Signing Secret

1. In your app settings, navigate to "Basic Information" in the left sidebar

2. Scroll down to "App Credentials"

3. Copy the "Signing Secret" - you'll need this to configure your channel in Stage5

Step 5: Add the Bot to Slack Channels

Your bot needs to be added to any Slack channels where you want it to respond:

1. In Slack, go to the channel where you want your agent active

2. Click the channel name at the top

3. Go to the "Integrations" tab

4. Click "Add apps"

5. Find and add your bot app

Alternatively, you can type /invite @YourBotName in the channel.

Step 6: Configure the Channel in Stage5

1. In your Stage5 project, in order to create or edit a channel manifest file, just instruct the assistant. For example: Connect the Customer Support Agent to a Slack channel. Make sure to have placeholders for all of the Secrets that are needed and I'll add them later. Behind the scenes the Stage5 Assistant will create it all, leaving you just to set the secrets.

2. Configure the required secrets. For more information see the "Storing Secrets" section.

Required Settings

You'll need to store these values as secrets in your project's Secret Vault:

• Bot Token Secret Key - The name of the secret storing your Bot User OAuth Token (from Step 2)

• Signing Secret Key - The name of the secret storing your Signing Secret (from Step 4)

Optional Settings

• Reply in Threads - If true, the bot will reply in threaded conversations instead of posting to the main channel. Defaults to false.

Example Channel Configuration

{
  "kind": "channel",
  "version": "1",
  "channel": {
    "type": "slack",
    "name": "Customer Support Slack Bot",
    "description": "AI assistant for customer support inquiries in Slack",
    "agentManifestPath": "agents/support-agent.json",
    "slackOptions": {
      "botTokenSecretKey": "slack-bot-token",
      "signingSecretKey": "slack-signing-secret",
      "replyInThreads": false
    },
    "selfRegistrationForExistingUsersEnabled": true,
    "selfRegistrationForNewUsersEnabled": false
  }
}

Step 7: Store Secrets

Before publishing, make sure you've stored the required secrets in your project's Secret Vault:

1. Store your Bot User OAuth Token (from Step 2) with the key name you specified as botTokenSecretKey

2. Store your Signing Secret (from Step 4) with the key name you specified as signingSecretKey

Step 8: Publish and Configure Webhook

1. Publish your channel to the desired environment (Production, Staging, etc.)

2. After publishing, Stage5 will provide you with a webhook URL

3. Go back to your Slack app settings → "Event Subscriptions"

4. Paste the webhook URL from Stage5 into the "Request URL" field

5. Slack will verify the URL - if successful, you'll see a green checkmark

6. Click "Save Changes"

Step 9: Test Your Channel

1. Go to any Slack channel where your bot is added (or send a direct message to the bot)

2. Send a test message

3. Your agent should respond within a few seconds

4. If you don't receive a response, check:

   • The bot is added to the channel

   • The webhook URL is correctly configured

   • Your secrets are stored correctly

   • The agent manifest path is correct

Configuration Options Reference

Channel Name

• Type: String

• Required: Yes

• Description: A descriptive name for your Slack channel (e.g., "Customer Support Bot")

Channel Description

• Type: String

• Required: Yes

• Description: Brief explanation of what this channel is for

Agent Manifest Path

• Type: String

• Required: Yes

• Description: Path to your agent manifest file (e.g., "agents/support-agent.json")

Bot Token Secret Key

• Type: String (secret key name)

• Required: Yes

• Description: The name of the secret in your Secret Vault that stores your Slack Bot User OAuth Token (starts with xoxb-)

Signing Secret Key

• Type: String (secret key name)

• Required: Yes

• Description: The name of the secret in your Secret Vault that stores your Slack Signing Secret

Reply in Threads

• Type: Boolean

• Required: No

• Default: false

• Description: When true, the bot will reply in threads instead of posting to the main channel. When a user posts a message, the bot's response will appear as a thread reply.

Self-Registration Options

See the main Channels documentation for details on:

• selfRegistrationForExistingUsersEnabled

• selfRegistrationForNewUsersEnabled

• selfRegistrationForExistingUsersDisabledMessage

• selfRegistrationForNewUsersDisabledMessage

• userDisabledMessage

• userDeletedMessage

Troubleshooting

Bot Not Responding

• Check bot is added to channel: The bot must be added as a member of any channel where it should respond

• Verify webhook URL: Ensure the webhook URL in Slack app settings matches the one from Stage5

• Check secrets: Verify your Bot Token and Signing Secret are correctly stored in the Secret Vault

• Review permissions: Make sure all required OAuth scopes are enabled

Webhook Verification Failing

• Ensure URL is correct: Copy the exact webhook URL from Stage5

• Check HTTPS: Slack requires HTTPS endpoints

• Timing: Wait a few seconds after publishing before configuring the webhook

Permission Errors

• Review scopes: Make sure all required bot token scopes are added in OAuth & Permissions

• Reinstall app: If you added new scopes, reinstall the app to your workspace

• Check workspace permissions: Ensure you have permission to install apps in your workspace

Messages Not Being Received

• Verify events: Ensure all required bot events are subscribed in Event Subscriptions

• Check channel type: Make sure you've subscribed to events for the channel types you're using (channels, groups, im, mpim)

Best Practices

1. Start with a test workspace: Before deploying to production, test your channel in a separate Slack workspace

2. Monitor usage: Keep an eye on how users interact with your bot

3. Use threads for long conversations: Enable "Reply in Threads" to keep channel feeds clean

4. Clear naming: Give your bot a descriptive name so users know what it does

5. Set expectations: Consider adding a welcome message or channel description explaining what the bot can help with

Security Considerations

• Never share your Bot Token or Signing Secret: Keep these secure and only store them in your Secret Vault

• Use environment-specific apps: Consider creating separate Slack apps for staging and production. Make sure to use different secret names for each environment. For example SLACK_BOT_TOKEN_DEV and SLACK_BOT_TOKEN_PROD.

• Review permissions regularly: Only grant the minimum permissions your bot needs

• Monitor for unusual activity: Regularly check your bot's message history for any suspicious activity