Slack

Connect your Aerostack bot to Slack using the Events API. The bot responds to direct messages and app mentions in channels.

Prerequisites

An Aerostack account with an existing bot (or create one during setup)
A Slack workspace where you have permission to install apps

Step 1: Create a Slack App

Go to api.slack.com/apps and click Create New App
Choose From scratch
Name your app and select your workspace
Navigate to Basic Information and note the Signing Secret

Step 2: Configure Bot Token Scopes

Navigate to OAuth & Permissions
Under Bot Token Scopes, add these scopes:
- chat:write — send messages
- app_mentions:read — detect @mentions
- im:history — read DM messages
- im:read — access DM conversations
- reactions:write — add emoji reactions (used for processing indicator)
Click Install to Workspace and authorize
Copy the Bot User OAuth Token (starts with xoxb-)

Step 3: Configure in Aerostack

Via Dashboard

Navigate to Bots in the sidebar
Click on your bot (or create a new one with platform set to Slack)
In the Platform Configuration section, enter:
- Bot Token — the xoxb- token from OAuth & Permissions
- Signing Secret — from Basic Information

Via API

curl -X POST https://api.aerostack.dev/api/bots \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Slack Support Bot",
    "platform": "slack",
    "workspace_id": "YOUR_WORKSPACE_ID",
    "system_prompt": "You are a helpful assistant in Slack. Keep responses concise.",
    "platform_config": {
      "bot_token": "xoxb-1234567890-abcdefghij",
      "signing_secret": "abc123def456..."
    }
  }'

Step 4: Activate

curl -X POST https://api.aerostack.dev/api/bots/YOUR_BOT_ID/activate \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

{
  "status": "active",
  "webhook_url": "https://api.aerostack.dev/api/bots/webhook/slack/bt_a1b2c3d4e5f6g7h8i9j0",
  "manual_setup_required": true
}

Step 5: Set the Webhook URL in Slack

Go to your app at api.slack.com/apps
Navigate to Event Subscriptions
Toggle Enable Events to On
In the Request URL field, paste the webhook URL from the activate response:
```
https://api.aerostack.dev/api/bots/webhook/slack/bt_YOUR_BOT_ID
```
Slack will send a verification challenge. Aerostack handles the url_verification event automatically — you should see a green checkmark.
Under Subscribe to bot events, add:
- message.im — Direct messages to the bot
- app_mention — When someone @mentions the bot in a channel
Click Save Changes

Step 6: Test

DM test: Send a direct message to your bot in Slack
Mention test: In any channel where the bot is a member, type @YourBot what can you help with?

The bot will add a brain emoji reaction to your message while processing, then respond in the same channel or thread.

Platform Config Fields

Field	Required	Description
`bot_token`	Yes	Bot User OAuth Token (`xoxb-...`)
`signing_secret`	Yes	Slack app signing secret for HMAC-SHA256 verification
`app_id`	No	Slack app ID (informational)
`respond_to_mentions`	No	Whether to respond to @mentions in channels (default: true)
`respond_to_dms`	No	Whether to respond to direct messages (default: true)
`respond_in_channels`	No	Whether to respond to non-mention messages in channels (default: false)
`use_threads`	No	Whether to respond in threads (default: false)

Webhook Verification

Slack uses signature verification with a replay protection window. The signing_secret you configure in Aerostack must match the Signing Secret from your Slack app’s Basic Information page. Aerostack automatically verifies every incoming request.

Retry Handling

Slack retries failed webhook deliveries automatically. Aerostack drops retries to prevent duplicate responses. If the first delivery genuinely fails (e.g., timeout), the user would need to send their message again.

Bot Mention Handling

When the bot is mentioned in a channel, Slack includes the mention as <@U12345678> in the message text. Aerostack automatically strips this prefix so the bot engine receives clean text.

Processing Indicator

When processing a message, the bot adds a “brain” emoji reaction to the triggering message. This gives users visual feedback that the bot is working on a response.

Message Limits

Slack recommends a 4000 character limit per message. Longer responses are automatically split at whitespace boundaries.

Troubleshooting

Issue	Solution
URL verification fails	Ensure the bot is activated in Aerostack before setting the URL in Slack.
Bot not responding to DMs	Verify `message.im` is subscribed under Event Subscriptions. Invite the bot to the DM conversation.
Bot not responding to @mentions	Verify `app_mention` is subscribed. The bot must be a member of the channel — invite it with `/invite @YourBot`.
Duplicate responses	Aerostack drops Slack retries by default. If duplicates persist, check for multiple webhook subscriptions.
”not_authed” errors in logs	Your `bot_token` may have been revoked. Reinstall the app and update the token.