> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thinnest.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Slack

> Deploy your thinnestAI agent to Slack as a bot that responds to messages and slash commands.

# Slack

Add your agent to Slack as a bot. Users can interact with it via direct messages, @mentions in channels, or slash commands.

## Prerequisites

* A Slack workspace where you have admin permissions
* Your agent created and tested in thinnestAI

## Setup

### Step 1: Create a Slack App

1. Go to [api.slack.com/apps](https://api.slack.com/apps)
2. Click **Create New App** > **From scratch**
3. Name your app (e.g., "Acme AI Assistant")
4. Select your workspace
5. Click **Create App**

### Step 2: Configure Bot Permissions

1. Go to **OAuth & Permissions** in the sidebar
2. Under **Bot Token Scopes**, add:
   * `chat:write` — Send messages
   * `app_mentions:read` — Read @mentions
   * `channels:history` — Read channel messages (for context)
   * `im:history` — Read DM history
   * `im:write` — Send DMs
3. Click **Install to Workspace** and authorize

### Step 3: Get the Bot Token

After installing, copy the **Bot User OAuth Token** (starts with `xoxb-`).

### Step 4: Configure Your Agent

1. Open your agent in thinnestAI
2. Go to the **Deploy** tab
3. Select **Slack**
4. Enter:
   * **Bot Token** — The `xoxb-` token from Slack
   * **Signing Secret** — Found in **Basic Information > App Credentials**
5. Click **Save & Enable**

### Step 5: Set Event Subscriptions

1. In your Slack app settings, go to **Event Subscriptions**
2. Toggle **Enable Events** on
3. Set the Request URL to:

```
https://api.thinnest.ai/webhooks/slack/events
```

4. Under **Subscribe to bot events**, add:
   * `app_mention` — Responds when @mentioned in channels
   * `message.im` — Responds to direct messages
5. Click **Save Changes**

### Step 6: Add Slash Command (Optional)

1. Go to **Slash Commands** in your Slack app settings
2. Click **Create New Command**
3. Configure:
   * **Command**: `/ask` (or your preferred command)
   * **Request URL**: `https://api.thinnest.ai/webhooks/slack/commands/YOUR_AGENT_ID`
   * **Description**: "Ask the AI assistant a question"
4. Click **Save**

## How It Works

### Event-Based (Mentions & DMs)

```
User @mentions bot or sends DM
        ↓
Slack sends event to /webhooks/slack/events
        ↓
thinnestAI verifies Slack signature
        ↓
Looks up agent by bot token match
        ↓
Extracts user info → auto-captures lead
        ↓
Routes message to agent (GraphExecutor)
        ↓
Agent responds → posted back to channel/DM
```

### Slash Command

```
User types /ask What is our refund policy?
        ↓
Slack sends command to /webhooks/slack/commands/{agent_id}
        ↓
Agent processes the question
        ↓
Response posted as reply in the channel
```

### Session Persistence

Each Slack user gets their own conversation session per channel.

Session ID format: `slack_{user_id}_{channel_id}`

### Automatic Lead Capture

Every Slack user is automatically captured as a lead with:

* **User ID**: Slack user identifier
* **Name**: From slash commands (display name)
* **Channel**: Stored in custom fields
* **Team ID**: Workspace identifier in custom fields
* **Platform**: `slack`
* **Deduplication**: One lead per Slack user per agent

## Agent Discovery

thinnestAI automatically matches Slack events to agents by finding agents with the matching `bot_token` in their configuration. This means one Slack app maps to one agent.

## Security

* **Signature verification**: Every event is verified using the Slack signing secret and `X-Slack-Signature` header
* **Challenge verification**: Initial URL verification is handled automatically
* **Event deduplication**: Slack may send events multiple times — the platform handles this gracefully
* **Token encryption**: Bot tokens are encrypted at rest

## Slash Command vs Events

| Feature     | Slash Command            | Events (Mention/DM)       |
| ----------- | ------------------------ | ------------------------- |
| Setup       | Per-command URL          | Single event URL          |
| Interaction | `/ask <question>`        | @bot or DM message        |
| Response    | Immediate reply          | Threaded reply            |
| Session     | Per-command (no history) | Full conversation history |
| Best for    | Quick questions          | Multi-turn conversations  |

## Troubleshooting

| Issue                   | Solution                                                              |
| ----------------------- | --------------------------------------------------------------------- |
| No response to @mention | Check Event Subscriptions are enabled and `app_mention` is subscribed |
| No response to DM       | Add `message.im` to bot events                                        |
| "Agent not found"       | Verify the bot token in agent config matches the Slack app            |
| Challenge error         | Ensure the webhook URL is accessible from Slack                       |
| Duplicate responses     | Check that only one agent has this bot token configured               |
| Slash command fails     | Verify the command URL includes the correct agent ID                  |