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

# Slack Integration

> Connect your crews to Slack so users can interact with them via mentions and slash commands

## Overview

Crewship can connect your deployments directly to Slack, allowing users to interact with your crews through `@mentions` and `/crewship` slash commands in any channel.

**How it works:**

1. You create a Slack app and connect it to your Crewship organization
2. Configure which deployment to invoke and how messages map to crew inputs
3. Users interact with your crew in Slack — the platform handles message routing, input mapping, and response delivery

## Setting Up

### 1. Create a Slack App

Go to **Settings > Integrations** in the [Crewship Console](https://console.crewship.dev) and click **Connect to Slack**.

You'll be guided through a setup flow:

1. **Configure your app** — Choose a name for your Slack app and bot display name
2. **Create the app in Slack** — Click the link to create a pre-configured Slack app with the correct scopes and event subscriptions
3. **Enter credentials** — Copy the **Client ID**, **Client Secret**, and **Signing Secret** from your Slack app's Basic Information page
4. **Authorize** — Complete the OAuth flow to install the app in your workspace

### 2. Set a Default Deployment

After connecting, select a **default deployment** from the dropdown next to your workspace. This is the crew that will be invoked when users `@mention` the bot without specifying a deployment name.

### 3. Configure Chat Mapping

In your `crewship.toml`, add a `[chat]` section to control how Slack messages are passed to your crew:

```toml crewship.toml theme={null}
[deployment]
framework = "crewai"
entrypoint = "src.support_bot.crew:SupportCrew"

[chat]
input_key = "query"
output_key = "messages"
```

Then redeploy:

```bash theme={null}
crewship deploy
```

See the [`[chat]` reference](/configuration/crewship-toml#chat) for all options.

## Interaction Modes

### @Mentions (Thread API)

When a user mentions your bot in a channel, it starts a threaded conversation:

```
@Crewship What's our refund policy?
```

* Creates a Crewship [thread](/guides/threads) behind the scenes
* Replies in the same Slack thread maintain conversation context
* Each follow-up message in the thread sends a new run with the full thread state

<Info>
  Requires the **Thread API** to be enabled on the deployment (enabled by default).
</Info>

### Slash Commands (Run API)

The `/crewship` slash command runs a single stateless execution:

```
/crewship run my-deployment What are the top trends in AI?
```

Format: `/crewship run <deployment-name> <input>`

Slash commands also support **JSON passthrough** — if the input is a valid JSON object, it's passed directly to the crew without wrapping:

```
/crewship run my-deployment {"topic": "AI trends", "format": "bullet-points"}
```

<Info>
  Requires the **Run API** to be enabled on the deployment (enabled by default).
</Info>

## Controlling Enabled APIs

Use `[apis]` in your `crewship.toml` to control which interaction modes are available:

```toml theme={null}
[apis]
enabled = ["thread"]   # Only @mentions — disable slash command runs
```

```toml theme={null}
[apis]
enabled = ["run"]      # Only slash commands — disable threaded mentions
```

When omitted, both APIs are enabled by default. See the [`[apis]` reference](/configuration/crewship-toml#apis) for details.

## Input and Output Mapping

### Input

When a Slack message arrives, it's wrapped into a JSON object using your `chat.input_key`:

| Message            | `input_key`         | Crew receives                   |
| ------------------ | ------------------- | ------------------------------- |
| "Tell me about AI" | `"input"` (default) | `{"input": "Tell me about AI"}` |
| "Tell me about AI" | `"topic"`           | `{"topic": "Tell me about AI"}` |

### Output

If `chat.output_key` is set, the platform extracts that field from the run result to post back to Slack. If not set, the full run output is used as the response.

## Example Configuration

A complete setup for a Slack-enabled customer support bot:

```toml crewship.toml theme={null}
[deployment]
framework = "crewai"
entrypoint = "src.support_bot.flows.chat_flow:ChatFlow"
python = "3.11"

[apis]
enabled = ["thread"]

[chat]
input_key = "query"
output_key = "messages"

[runtime]
timeout = 120
```

## Managing Workspaces

In **Settings > Integrations**, you can:

* **Enable/disable** a workspace connection without removing it
* **Change the default deployment** at any time
* **Disconnect** a workspace entirely

## Related

<CardGroup cols={2}>
  <Card title="[chat] Config" icon="gear" href="/configuration/crewship-toml#chat">
    Chat input/output mapping reference
  </Card>

  <Card title="[apis] Config" icon="gear" href="/configuration/crewship-toml#apis">
    API enablement reference
  </Card>

  <Card title="Threads" icon="comments" href="/guides/threads">
    Multi-turn conversation context
  </Card>

  <Card title="Building a Chatbot" icon="robot" href="/guides/chatbot">
    Build a thread-based chatbot
  </Card>
</CardGroup>