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

# Slack

> Connect your AI assistant to a Slack workspace

Connect your Coral assistant to Slack to chat with it via DMs, mentions in channels, and threaded replies.

Coral offers two ways to connect Slack:

<CardGroup cols={2}>
  <Card title="One-Click Connect (Recommended)" icon="bolt">
    Click **"Connect with Slack"** and authorize Coral's Slack app in your workspace. No manual setup required.
  </Card>

  <Card title="Bring Your Own App" icon="wrench">
    Create your own Slack app for full customization of the bot identity, permissions, and access policies.
  </Card>
</CardGroup>

***

## Option A: One-Click Connect (Managed)

This is the fastest way to get Slack working. Coral handles the app, tokens, and event routing for you.

### Setup

1. Open the [Coral dashboard](https://app.coral.inc) and go to the **Integrations** page.
2. Click on the **Slack** card and select the **"Connect with Slack"** option.
3. You'll be redirected to Slack's authorization page.
4. Select the workspace you want to connect and click **"Allow"**.
5. You'll be redirected back to Coral with Slack connected.

### Capabilities

Once connected, Coral's Slack app provides:

* **Direct Messages** — Chat with your AI assistant in DMs.
* **Channel Mentions** — Mention the bot in any channel it's been added to.
* **Thread Replies** — All responses are threaded automatically to keep channels clean.

### Disconnect

To disconnect, click **"Disconnect"** on the Slack integration card. This revokes the OAuth token and removes the connection.

<Note>
  Each Slack workspace can only be connected to one Coral instance at a time.
</Note>

***

## Option B: Bring Your Own App (BYOA)

Use this option if you want full control over the bot's identity, permissions, and access policies. You'll create your own Slack app and provide the tokens to Coral.

### Step 1: Create a Slack App

1. Go to the [Slack App Directory](https://api.slack.com/apps) and click **"Create New App"**.
2. Choose **"From scratch"**.
3. Enter an app name (e.g., "My AI Assistant") and select your workspace.
4. Click **"Create App"**.

### Step 2: Enable Socket Mode

Socket Mode lets the bot receive events over a WebSocket connection instead of requiring a public URL.

1. In the left sidebar, click **"Socket Mode"**.
2. Toggle **"Enable Socket Mode"** to on.
3. You'll be prompted to create an **App-Level Token**. Name it (e.g., "coral-socket") and add the scope `connections:write`.
4. Click **"Generate"** and copy the token. It starts with `xapp-`.

### Step 3: Configure Bot Permissions

1. In the left sidebar, go to **"OAuth & Permissions"**.
2. Under **Bot Token Scopes**, add the following:
   * `app_mentions:read`
   * `channels:history`
   * `channels:read`
   * `chat:write`
   * `groups:history`
   * `groups:read`
   * `im:history`
   * `im:read`
   * `im:write`
   * `mpim:history`
   * `mpim:read`
   * `users:read`

### Step 4: Enable Event Subscriptions

1. In the left sidebar, click **"Event Subscriptions"**.
2. Toggle **"Enable Events"** to on.
3. Under **"Subscribe to bot events"**, add:
   * `app_mention`
   * `message.channels`
   * `message.groups`
   * `message.im`
   * `message.mpim`

### Step 5: Install the App

1. In the left sidebar, go to **"Install App"**.
2. Click **"Install to Workspace"** and authorize.
3. Copy the **Bot User OAuth Token**. It starts with `xoxb-`.

### Step 6: Connect in Coral

1. Open the [Coral dashboard](https://app.coral.inc) and go to the **Integrations** page.
2. Click on the **Slack** card and choose the **"Bring Your Own App"** option.
3. Enter both tokens:
   * **Bot Token** (`xoxb-...`)
   * **App Token** (`xapp-...`)
4. Click **"Connect"**.

Coral validates the tokens against the Slack API, then prompts you to configure access policies.

### Step 7: Configure Access Policies

After validation, you can configure how the bot responds:

| Setting             | Options                     | Description                                    |
| ------------------- | --------------------------- | ---------------------------------------------- |
| **DM Policy**       | Open / Allowlist / Disabled | Who can DM the bot                             |
| **Channel Policy**  | Open / Allowlist / Disabled | Which channels the bot responds in             |
| **Require Mention** | Yes / No                    | Whether the bot must be @mentioned in channels |

* **Open** — The bot responds to everyone / in every channel it has access to.
* **Allowlist** — The bot only responds to specific users / in specific channels you select.
* **Disabled** — The bot ignores DMs or channel messages entirely.

After configuring, click **"Save & Connect"** to finalize.

## Managing Your Slack Integration

You can update access policies at any time by clicking **"Edit access policies"** on the connected card.

To disconnect, click **"Disconnect"**. For BYOA, this removes the tokens from your sandbox. For managed Slack, this revokes the OAuth token.

## Troubleshooting

| Problem                          | Solution                                                                                                  |
| -------------------------------- | --------------------------------------------------------------------------------------------------------- |
| "Workspace already connected"    | Each Slack workspace can only link to one Coral instance. Disconnect from the other instance first.       |
| Bot doesn't respond in a channel | Invite the bot to the channel first (`/invite @botname`). Also check that the channel policy allows it.   |
| Bot doesn't respond to DMs       | Check that the DM policy is set to "Open" or that the user is in the allowlist.                           |
| "Invalid token" error            | Make sure you're using the correct token types: `xoxb-` for Bot Token and `xapp-` for App Token.          |
| Socket Mode connection drops     | Ensure Socket Mode is enabled in your Slack app settings and the App Token has `connections:write` scope. |

## Security

* **BYOA**: Both tokens are stored exclusively inside your sandbox's configuration. They never pass through Coral's servers.
* **Managed**: The bot token is encrypted with AES-256-GCM and stored on Coral's servers. The encryption key is derived per-user and never stored alongside the token.
* Slack webhook signatures are verified using HMAC-SHA256 with 5-minute replay protection.