# Slack

> Set up an Aerostack bot on Slack — create a Slack app, configure Event Subscriptions, and connect to your workspace.

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

**Manual setup required.** Slack does not allow setting webhook URLs programmatically. You must configure the Event Subscriptions URL manually in the Slack App settings. Aerostack provides the URL — you paste it in.

---

## 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

1. Go to [api.slack.com/apps](https://api.slack.com/apps) and click **Create New App**
2. Choose **From scratch**
3. Name your app and select your workspace
4. Navigate to **Basic Information** and note the **Signing Secret**

---

## Step 2: Configure Bot Token Scopes

1. Navigate to **OAuth & Permissions**
2. 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)
3. Click **Install to Workspace** and authorize
4. Copy the **Bot User OAuth Token** (starts with `xoxb-`)

---

## Step 3: Configure in Aerostack

### Via Dashboard

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

### Via API

```bash
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

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

Response:

```json
{
  "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

1. Go to your app at [api.slack.com/apps](https://api.slack.com/apps)
2. Navigate to **Event Subscriptions**
3. Toggle **Enable Events** to **On**
4. 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
   ```
5. Slack will send a verification challenge. Aerostack handles the `url_verification` event automatically — you should see a green checkmark.
6. Under **Subscribe to bot events**, add:
   - `message.im` — Direct messages to the bot
   - `app_mention` — When someone @mentions the bot in a channel
7. Click **Save Changes**

If the URL verification fails, ensure your bot is **activated** in Aerostack before pasting the URL. The webhook endpoint must be live to respond to Slack's challenge.

---

## 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. |