What you can do
- Post messages: agents can send messages to any channel the bot has been added to, using the
chat:writescope. - 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 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
Create a new Slack app
Go to 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.
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.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.
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.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.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.
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.What Circuit accesses
The bot token authorizes Circuit to act as the bot user you created. Circuit requests the minimum scope needed:| 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. |
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.
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) 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.
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, 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.
Troubleshooting
"not_in_channel" error when the agent tries to post
"not_in_channel" 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.
"invalid_auth" or "token_revoked" error
"invalid_auth" or "token_revoked" 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) and paste the new token into Circuit.
"channel_not_found" when posting to the default channel
"channel_not_found" 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.App creation is blocked: 'Your workspace doesn't allow new apps'
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.
"missing_scope" error mentioning a scope other than chat:write
"missing_scope" 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.Reference
- Auth method: Slack bot token (user-supplied)
- Token prefix:
xoxb- - Scopes requested:
chat:write - Agent property:
slack_default_channel(Slack channel ID, for exampleC0123456789) - Where you create the app: api.slack.com/apps
- Slack’s own docs: Tokens, Quickstart, Scopes reference