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

# Connect to Slack

> Connect a Slack workspace to Overcut, register channels per project, and trigger workflows from team conversations.

Slack lets your team start and continue Overcut workflows from the channels where work already happens. You connect Slack once at the workspace level, then register the channels each project can use. Once a channel is registered, project workflows can be triggered by `@overcut` mentions, the `/overcut` slash command, or (in Active mode) regular channel messages.

## What you can do

* Trigger workflows from a registered Slack channel using `@overcut` mentions or the `/overcut` command.
* Optionally treat every top-level channel message as a workflow event (for incident channels, alert channels, or routing on bot posts).
* Give agents Slack messaging capabilities so they can reply, edit, read, and react in the channel where the workflow was triggered.
* Continue an [interactive session](/docs/reference/interactive-sessions) inside a Slack thread the same way it works on a PR or issue.

## Setup overview

Slack works at two levels in Overcut. Each level is configured separately.

| Level     | Where                                   | What you configure                                                               |
| --------- | --------------------------------------- | -------------------------------------------------------------------------------- |
| Workspace | **Workspace → Integrations**            | The OAuth connection to your Slack workspace. Done once per Overcut workspace.   |
| Project   | **Project Settings → Project Channels** | Which Slack channels this project can use, and how each channel routes messages. |

See [Multi-Project Workspaces](/docs/concepts/multi-project-workspaces) for the broader workspace-vs-project boundary.

## Connect Slack to your workspace

<Steps>
  <Step title="Open workspace Integrations">
    From the workspace sidebar (no project selected), go to **Integrations**.
  </Step>

  <Step title="Connect Slack">
    In the providers list, find **Slack** and click connect. You'll be redirected to Slack to authorize the Overcut app for your Slack workspace.
  </Step>

  <Step title="Approve the OAuth scopes">
    Approve the requested scopes in Slack. After approval you return to Overcut and the Slack workspace appears in the connected providers list.
  </Step>
</Steps>

You can connect more than one Slack workspace if your team uses several. When you register channels later, you pick which Slack workspace each channel belongs to.

## Register channels in a project

Channel registration is per project. A channel must be registered in a project before that project's workflows can be triggered from it or post into it.

<Steps>
  <Step title="Open Project Channels">
    Inside a project, go to **Project Settings → Project Channels**.
  </Step>

  <Step title="Add channels">
    Click **Add Channel**, pick the Slack workspace under **Messaging workspace**, then select one or more channels from the list. Click **Add Selected Channels** to register them.
  </Step>

  <Step title="Confirm the channel appears">
    Registered channels show in the Project Channels list with the default routing mode (**Mentions only**).
  </Step>
</Steps>

<Note>
  Public channels are joined automatically when you add them. For **private channels**, invite the Overcut bot first by running `/invite @overcut` in the channel. Private channels the bot has not been invited to do not appear in the picker.
</Note>

### Project-scoped channel behavior

* A channel registered in one project is only available to that project's workflows.
* The same Slack channel can be registered in more than one project when teams share a channel across workflows.
* Removing a channel from one project does not remove it from any other project.

## Channel routing modes

Each registered channel has a **routing mode** that controls which messages reach your workflows. Open the channel row in **Project Channels** to change it.

| Mode                        | When workflows can fire                                                                                                                                 |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Mentions only** (default) | `@overcut` mentions, `/overcut` slash commands, and thread replies that continue an active session. All other channel chatter is ignored.               |
| **Watch all messages**      | Every new top-level message in the channel becomes a `channel_message` event that can match a workflow trigger. Mentions and slash commands still work. |

Most channels should stay on **Mentions only**. Switch to **Watch all messages** when you want the channel itself to be the event source: for example, incident channels where every alert from PagerDuty or Datadog should be evaluated, or product channels where new top-level posts should be triaged.

<Warning>
  **Watch all messages** routes every top-level message through trigger evaluation, including posts from other bots. Pair it with trigger conditions (sender, keywords, channel) so high-traffic channels don't flood agents with runs. Switching a channel into this mode requires a second confirmation.
</Warning>

## Trigger workflows from Slack

Once a channel is registered, the same trigger types you use for repository and ticket events apply.

| Surface                                                  | Event type        | What it matches                                                                                                                                                                                                                                                                  |
| -------------------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@overcut <message>` mention                             | `mention`         | A workflow whose trigger event type is **mention** and whose channel filters match this channel. Use this for conversational requests.                                                                                                                                           |
| `/overcut <command> [args]` slash command                | `slash_command`   | Slack apps register only their own slash command, so the bot prefix is always `/overcut`. The next token (`<command>`) is matched against the **Slash Command** field on a workflow's Manual trigger. See the [Slash Command Guide](/docs/workflows/trigger-with-slash-command). |
| Top-level channel message (Watch all messages mode only) | `channel_message` | A workflow with a `channel_message` trigger on this channel. Use trigger conditions to filter by sender, keywords, or channel.                                                                                                                                                   |
| Thread reply                                             | `thread_reply`    | If an [interactive session](/docs/reference/interactive-sessions) is active for the thread, the reply routes to that session. Otherwise the message is ignored.                                                                                                                  |

<Note>
  A plain `@overcut` mention and `/overcut <command>` are **different trigger types**. A mention-trigger workflow won't fire on a slash command, and a slash-command workflow won't fire on a plain mention. Configure each surface with the matching trigger event type.
</Note>

See [Triggers](/docs/workflows/triggers) for the full trigger model and [Trigger with Slash Command](/docs/workflows/trigger-with-slash-command) for a step-by-step slash command setup.

<Tip>
  Use `/overcut` when you want an explicit command in a busy channel. Use `@overcut` when the request fits naturally into an ongoing discussion.
</Tip>

## What agents can do in a Slack channel

When a workflow runs in a registered channel, you can give the agent Slack messaging capabilities so it can participate in the conversation. These are configured per agent in **Agent Roles**: see [Agent Tools Reference](/docs/reference/tools).

| Action               | What the agent can do                                                                  |
| -------------------- | -------------------------------------------------------------------------------------- |
| **Post message**     | Post a reply in the registered channel to share updates, answers, or workflow results. |
| **Read messages**    | Read recent channel messages to understand the discussion before responding.           |
| **Edit message**     | Update a message the agent posted earlier to keep responses accurate.                  |
| **Manage reactions** | Add or remove emoji reactions on messages in the channel.                              |

Agents can only act in channels that are registered to the project they belong to.

## Interactive sessions in Slack

The same [comment routing rules](/docs/reference/interactive-sessions#comment-routing-rules) that apply to PR and issue threads apply to Slack threads in registered channels. While a session is active for a thread, new replies in that thread route to the session instead of starting a new workflow. Use `/done` to end the session gracefully, or `/quit` to terminate the workflow.

## Related

* [Multi-Project Workspaces](/docs/concepts/multi-project-workspaces): how workspace integrations and project settings fit together.
* [Triggers](/docs/workflows/triggers): the full trigger model.
* [Trigger with Slash Command](/docs/workflows/trigger-with-slash-command): step-by-step slash command setup.
* [Agent Tools Reference](/docs/reference/tools): the Slack messaging actions you can give an agent.
* [Interactive Sessions](/docs/reference/interactive-sessions): how routing into active sessions works.