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

# Slack

> Connect Circuit to Slack so agents can post messages to your workspace.

The Slack integration lets agents post messages into channels in your Slack workspace. Unlike Circuit's OAuth-based integrations, Slack uses a bot token that you generate from a Slack app you create in your own workspace, then paste into Circuit.

## What you can do

* **Post messages**: agents can send messages to any channel the bot has been added to, using the `chat:write` scope.
* **Default channel**: set a default channel per agent so the agent posts to the same place unless told otherwise.
* **Stay scoped to your workspace**: the bot only operates in the Slack workspace where you installed the app.

## Before you start

* A Slack workspace where you have permission to create and install apps. Some workspaces restrict app installation to owners or admins. See [For IT and security teams](#for-it-and-security-teams) below.
* The channel ID for the channel where the agent should post by default. You can find this after the app is installed.
* About five minutes to create the Slack app and copy the token.

## Connect Slack

<Steps>
  <Step title="Create a new Slack app">
    Go to [api.slack.com/apps](https://api.slack.com/apps) and click **Create New App**. Choose **From scratch**, name the app something recognizable (for example, "Circuit"), pick the workspace you want to connect, and click **Create App**.
  </Step>

  <Step title="Add the chat:write bot scope">
    In the app's left sidebar, open **OAuth & Permissions**. Scroll to **Scopes** and, under **Bot Token Scopes**, add `chat:write`. This is the minimum scope Circuit needs to post messages. Add other scopes only if you understand why you are doing so.
  </Step>

  <Step title="Install the app to your workspace">
    Scroll back to the top of the **OAuth & Permissions** page and click **Install to Workspace**. Slack shows a consent screen listing the scopes the app requests. Click **Allow**.
  </Step>

  <Step title="Copy the Bot User OAuth Token">
    After installation, Slack returns you to **OAuth & Permissions**. Copy the **Bot User OAuth Token**. It starts with `xoxb-`. Treat it like a password.
  </Step>

  <Step title="Paste the token into Circuit">
    In Circuit, open **Settings** > **Integrations** and choose **Slack**. Paste the `xoxb-` token into the token field and save. The integration status changes to **Connected**.
  </Step>

  <Step title="Add the bot to channels">
    In Slack, open your app's direct message, click the three-dot menu in the top-right, then click **Open app details**. Click **Add this app to a channel**, select each channel the agent should post to, and confirm. The bot can only post to channels it has been added to, including private channels.
  </Step>

  <Step title="Set the default channel on the agent">
    In Circuit, open the agent that should use Slack and set the `slack_default_channel` property to the channel's ID (for example, `C0123456789`). To find a channel ID, right-click the channel name in Slack, choose **Copy link**, and use the trailing segment of the URL. The default channel is where the agent posts when no channel is specified at call time.
  </Step>
</Steps>

## What Circuit accesses

The bot token authorizes Circuit to act as the bot user you created. Circuit requests the minimum scope needed:

```
chat:write
```

| Scope        | Why Circuit needs it                                                                                                                          |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `chat:write` | Post messages as the bot user into channels the bot has been added to. This is the only Slack capability Circuit requires for the agent tool. |

<Note>
  The bot can only post into channels it is a member of. It cannot read message history, view users, or read files unless you explicitly add scopes for those capabilities, which Circuit does not require.
</Note>

## For IT and security teams

Unlike Circuit's Microsoft, Google, Atlassian, and Salesforce integrations, the Slack integration is **not** a Circuit-published OAuth app installed across your workspace. The Slack app lives entirely in your own workspace, and the token you paste into Circuit is one you created and control.

* **Who can install apps**: Slack workspace owners and admins can restrict who creates and installs apps under **Settings & administration** > **Manage apps** > **App management settings**. If creation is restricted, an owner or admin needs to create the Circuit Slack app on a user's behalf and share the token.
* **App approval**: workspaces that require app approval will queue the new app for review. An admin must approve it before the install step completes.
* **Token format**: bot tokens start with `xoxb-`. They are encrypted at rest in Circuit's database and never returned to the browser.
* **Revocation**: revoking the app in Slack (see [Disconnect or rotate access](#disconnect-or-rotate-access)) immediately invalidates the token. Circuit's next API call will fail and the integration status will move to **Disconnected**.
* **Audit**: workspace owners can review the bot's actions under **Settings & administration** > **Manage apps** > pick the app > **Activity**.

See [Integration security and admin consent](/it/integration-security) for how Circuit handles credentials across all integrations.

## Disconnect or rotate access

To disconnect from Circuit's side, open **Settings** > **Integrations** > **Slack** in Circuit and click **Disconnect**. Circuit deletes the stored token immediately.

To revoke from Slack's side, go to [api.slack.com/apps](https://api.slack.com/apps), open your Circuit app, and either:

* **Rotate the token**: under **OAuth & Permissions**, click **Reinstall to Workspace**. Slack issues a new token; the old one stops working. Paste the new token into Circuit.
* **Revoke entirely**: under **Basic Information**, click **Delete App**. The token is invalidated and Circuit loses access on the next call.

Workspace admins can also revoke the app for all users under **Settings & administration** > **Manage apps**.

## Troubleshooting

<AccordionGroup>
  <Accordion title="&#x22;not_in_channel&#x22; error when the agent tries to post">
    The bot is not a member of the target channel. In Slack, open your app's direct message, click the three-dot menu, click **Open app details**, then click **Add this app to a channel** and choose the target channel. This is the most common Slack integration error.
  </Accordion>

  <Accordion title="&#x22;invalid_auth&#x22; or &#x22;token_revoked&#x22; error">
    The token has been rotated, revoked, or the app was deleted in Slack. Generate a fresh token by reinstalling the app to your workspace (see [Disconnect or rotate access](#disconnect-or-rotate-access)) and paste the new token into Circuit.
  </Accordion>

  <Accordion title="&#x22;channel_not_found&#x22; when posting to the default channel">
    The `slack_default_channel` value is wrong or the channel was archived. Right-click the channel in Slack, copy the link, and use the trailing identifier (starts with `C` for public, `G` for private group, `D` for DM). Update the agent property and save.
  </Accordion>

  <Accordion title="App creation is blocked: 'Your workspace doesn't allow new apps'">
    Your Slack workspace requires admin approval for new apps. Ask a workspace owner or admin to either create the app on your behalf or approve it from **Settings & administration** > **Manage apps** > **App management settings**.
  </Accordion>

  <Accordion title="&#x22;missing_scope&#x22; error mentioning a scope other than chat:write">
    The agent is calling a Slack capability beyond posting messages. Confirm which tool was invoked. Circuit's standard Slack tool only requires `chat:write`. If you intentionally added extra scopes, reinstall the app after adding them, then paste the new token into Circuit.
  </Accordion>
</AccordionGroup>

## Reference

* **Auth method**: Slack bot token (user-supplied)
* **Token prefix**: `xoxb-`
* **Scopes requested**: `chat:write`
* **Agent property**: `slack_default_channel` (Slack channel ID, for example `C0123456789`)
* **Where you create the app**: [api.slack.com/apps](https://api.slack.com/apps)
* **Slack's own docs**: [Tokens](https://docs.slack.dev/authentication/tokens), [Quickstart](https://docs.slack.dev/quickstart), [Scopes reference](https://api.slack.com/scopes)