Skip to content

Set up Slack integration

This guide shows you how to connect Slack to a Control Center workspace: by adding the shared Control Center app, or with an app of your own that Control Center creates for you or that you build yourself.

For a guided first run, see Bridge Slack to your workspace.

  • The owner or admin role in the Control Center workspace — connecting a chat app is a workspace-settings change
  • Permission to create and install apps in the Slack workspace
  • Nothing publicly reachable: your own app connects out over Socket Mode and the shared app’s events reach the server through a long poll to Control Center Connect, so the server needs no inbound port, tunnel, or domain

A workspace runs on exactly one of these at a time.

Mode Needs You get
Shared Control Center app The workspace’s sign-in apps run through Control Center Connect (the server’s choice in Settings → Server → Single sign-on, or the workspace’s own on Settings → Workspace → Integrations) and Connect serves Slack One click and a Slack sign-in. No app to create, no token to paste, nothing to rotate
Your own app A Slack app in your Slack workspace, made one of the three ways below Your own bot name, descriptions and slash command, editable from Control Center
  1. In Control Center, go to Settings → Workspace → Integrations and scroll to the Chat bridges card
  2. On the Slack block, find the Add Control Center to Slack row and click Add to Slack
  3. Your browser opens Slack. Sign in with Slack, pick the Slack workspace and approve the install
  4. When the browser shows a code, enter it in the dialog Control Center left open. If the browser hands you back to the app by itself, there is nothing to type
  5. A toast names the Slack workspace the app was added to, and the Slack block shows the connection as running on the shared Control Center app

Only a workspace admin can add the app. The row says why it cannot start when this workspace’s sign-in apps are its own apps rather than Connect, when your Connect has no Slack app, or when this workspace already has its own Slack app connected.

How it differs from your own app:

  • Slack sends the shared app’s events to Connect. Connect keeps only a reference (team, channel and message id) and drops the message text; the server long-polls Connect for references and reads each message from Slack itself. A slash command’s text does pass through Connect, which is why /cc ticket only drafts
  • The bot token is sealed for this server and renewed through Connect, so there is no token to paste or rotate
  • The bot’s name, descriptions and slash command are the shared app’s. The Slack row says the connection runs on the shared app and offers no Customise bot
  • A Slack workspace is bound to one Control Center server at a time. Adding the app from another server moves it there and this server’s connection stops

To switch between modes, disconnect and connect the other way.

Path You provide Control Center does
Guided An app configuration token (xoxe-…) Creates the app with the right scopes, events, Socket Mode and slash command; hands you the two steps Slack has no API for
Create in Slack Nothing Opens Slack with the same configuration pre-filled; you pick a workspace and confirm
By hand The finished app’s tokens Verifies them and connects

The guided path is the only one that also leaves the app manageable from Control Center, which is what enables Customise the chat bot. A Create in Slack app can be promoted to a managed one later by pasting a configuration token in the connect dialog.

Your own app’s events never pass through Connect: Socket Mode delivers them straight to this server.

Option A: let Control Center create the app

Section titled “Option A: let Control Center create the app”
  1. Generate an app configuration token pair at api.slack.com/apps and copy the refresh token (xoxe-…)
  2. In Control Center, go to Settings → Workspace → Integrations and scroll to the Chat bridges card
  3. On the Slack block, click Create app for me
  4. Paste the token, adjust the app name, bot name, descriptions and slash command, then click Create app
  5. Follow the two remaining steps the dialog shows, each as a link into Slack:
    • Basic Information → App-Level Tokens: generate a token with the connections:write scope (xapp-…)
    • Install App: install to the workspace and copy the Bot User OAuth Token (xoxb-…)
  6. Click Paste the credentials and continue with Connect

The configuration token rotates on every use. Control Center stores the rotated value as it goes, so you never have to paste it again.

Same app, no configuration token — Slack hands you its own create screen with the whole manifest already filled in.

  1. In Control Center, go to Settings → Workspace → Integrations and scroll to the Chat bridges card
  2. On the Slack block, click Create app for me
  3. Adjust the app name, bot name, descriptions and slash command — these travel with the link
  4. Click Create in Slack. Your browser opens Slack’s app-creation page with the configuration pre-filled
  5. Pick the Slack workspace and confirm. The scopes, events, Socket Mode and slash command are already correct
  6. Back in Control Center, follow the two remaining steps the dialog shows:
    • Basic Information → App-Level Tokens: generate a token with the connections:write scope (xapp-…)
    • Install App: install to the workspace and copy the Bot User OAuth Token (xoxb-…)
  7. Click Paste the credentials and continue with Connect

Slack does not report which app it created, so Control Center does not learn the app id and the links in step 6 go to your app list rather than straight to that app. Customise bot needs a configuration token.

Create an app at api.slack.com/apps, then set it up as follows.

Socket Mode: enable it and leave every request URL empty. Slack refuses a manifest that asks for both Socket Mode and webhook delivery.

Bot token scopes (OAuth & Permissions):

app_mentions:read
assistant:write
channels:history
chat:write
commands
groups:history
im:history
users:read
users:read.email

Event subscriptions (bot events):

app_home_opened
app_mention
message.channels
message.groups
message.im

message.channels and message.groups are what make a reply inside an already-bridged Slack thread work. Without them, only the first mention ever arrives.

Slash command: /cc (any name works — the bridge uses whatever command it was last invoked with).

App Home: enable the Messages tab and leave it writable, so members can DM the bot.

Tokens: generate an app-level token with connections:write, then install the app and copy the bot user OAuth token.

This is how your own app’s tokens reach Control Center. The shared app needs none of it.

  1. Go to Settings → Workspace → Integrations and scroll to the Chat bridges card
  2. On the Slack block, click Connect Slack
  3. Fill in the fields:
Field Value Where it lives in Slack
Bot user OAuth token xoxb-… OAuth & Permissions → Bot User OAuth Token
App-level token xapp-… Basic Information → App-Level Tokens (connections:write)
App configuration refresh token (optional) xoxe-… The app configuration token pair on api.slack.com/apps

The prefix of each value is checked on both sides before anything is sent, so a value pasted into the wrong box is refused with the same sentence either way.

  1. Click Connect

Control Center verifies the bot token with Slack’s auth.test before storing anything, so a typo is reported to you rather than becoming a socket that quietly never works. The app-level token can only be proven by opening the socket, so a bad one shows up a moment later as a connection error on the same row.

Without the optional app configuration token, the connection works fine — you just cannot edit the bot from Control Center.

  • Stores the credentials in the workspace’s own directory, beside its database, owner-readable only. They never travel back to a client. For the shared app, that is the sealed grant; the short-lived bot token it renews into stays in memory
  • Starts receiving mentions, Slack thread replies, DMs and slash commands: over one Socket Mode connection for your own app, or through the server’s one Connect long poll for the shared app
  • Re-arms every Slack thread that was bridged before, so a reconnect continues existing conversations instead of stranding them
  • Costs nothing for workspaces that have no chat app: no socket, no timers, no traffic

The Slack row shows a status tag: Live, Connecting…, Connection error (with Slack’s own error next to it), or Not connected. To check end to end:

  1. In Slack, invite the bot to a channel: /invite @your-bot-name
  2. Mention it with a request
  3. A Slack thread reply appears and a matching space appears in Control Center

Every member who wants to use the bridge then links their own account — see Link your Slack account.

Above the streamed words sits one grouped card with a row per step. Setup is one row whose title moves from Working on it… to Cloning … to Starting the agent…. Reasoning adds a Thinking… row; when that step finishes, a short thought can appear on it. Each tool is its own row (Read lib/main.dart). The answer arrives as ordinary text under the card. The card turns complete when the turn finishes and errored when the run failed, was interrupted, or hit its turn limit.

The card starts the moment the bot accepts the mention — Working on it… — so the Slack thread is not silent while the workspace is still being built. Your first mention in a Slack channel creates the conversation, which clones the repos the agent works in, so that setup row then reads Cloning acme/widgets…, then Setting up Reviewer…, then Starting the agent…, then a Thinking… row once the agent is actually reasoning. On a big repository that first setup takes a while; the card is how you can tell it is working rather than ignoring you. Later mentions in the same Slack thread still open with Working on it…, then skip the clone steps because the workspace is already there.

Reasoning as a wall of text and tool output, never leave Control Center — the thought on the Thinking… row is a short line, not a transcript. View in Control Center on the card opens the full conversation in the desktop app — the link goes to your own Control Center server, which hands the browser over to the app.

If nothing happens when you click it, the server that sent the message is not reachable from the machine you clicked on (a loopback-only server clicked from a phone, for example), or Control Center is not running there. A server with no reachable address sends a card with no button rather than one that leads nowhere.

Any linked member with a writing role can propose a ticket from Slack:

/cc ticket Fix the flaky login test | It fails on CI about once a day.

Text before the | is the title, text after it the description. The bot replies that it drafted the ticket. Nothing is created yet and no ticket automation fires: the draft waits for you in Settings → You → Profile → Ticket drafts from chat, where you can correct the title and description, then click Create ticket or Discard.

  • Only the member who ran the command sees the draft
  • A draft you leave is dropped after a day. Drafts live in memory, so a server restart drops them too
  • The card appears only while you have drafts

A command’s text cannot be re-read from Slack and, on the shared app, it travelled through Connect. Creating the ticket in Control Center is what makes it yours.

This applies to your own app. The shared app has no token to rotate.

Re-paste the new value in the connect dialog and click Connect. Connecting replaces whatever connection was running for this workspace, so the socket is re-dialled with the new credentials.

The two required tokens have to be present on every connect. The optional app configuration token keeps its stored value when you leave the box empty, so rotating a bot token never costs you the ability to edit the app.

Click Disconnect on the Slack row (admins only). The connection closes and the credentials are forgotten. For the shared app, Control Center also uninstalls the bot from the Slack workspace and releases its binding to this server.

Space and user links deliberately survive: reconnecting the same app restores every bridged Slack thread. They are workspace-scoped rows, so deleting the workspace removes them anyway.

Read the error shown next to the tag. A rejected credential (invalid_auth, not_authed, token_revoked, account_inactive) is terminal — the bridge stops retrying and waits for new tokens, because retrying a revoked token forever only rate-limits you. Re-paste the tokens in the connect dialog.

A missing_scope error means the app is installed with fewer scopes than the bridge needs. Add the missing scope, reinstall the app in Slack, then reconnect.

Anything transient (a dropped socket, a Slack hiccup) reconnects on its own with exponential backoff capped at 30 seconds and Slack’s routine socket rotation does not escalate that backoff.

  • Is the bot in the channel? Slack only delivers channel messages to apps that are members. Run /invite @your-bot-name
  • Are you linked? An unlinked member gets a reply in that Slack thread explaining how to link. See Link your Slack account
  • Are you a member of the workspace with a writing role? A viewer or guest is told their role is read-only. The bridge never starts work on behalf of someone it cannot attribute
  • Does the workspace have any agents? With no agents, the message is stored but has nobody to answer it

It answers in a channel but ignores plain messages

Section titled “It answers in a channel but ignores plain messages”

That is intended. Outside a DM, the bridge only acts on a message that mentions the bot, or a reply inside a Slack thread it already owns. Everything else is other people’s conversation.

Replies arrive as one big message instead of streaming

Section titled “Replies arrive as one big message instead of streaming”

The row says “Live streaming is off for this Slack app — replies arrive as one message.” Slack’s streaming replies need the Agents & AI Apps feature on a paid plan; when Slack refuses it, the bridge stops asking for the rest of that connection’s life and posts whole replies instead. Nothing is lost — the full transcript is always in Control Center.

Streaming also needs a Slack thread anchor, so a reply that has no Slack thread to grow in is posted whole. The task card still arrives either way: on a whole reply it rides the same message, already complete.

Slack’s task cards are part of the same new Agents & AI Apps surface as streaming and Slack only refuses at call time. When it does, Control Center keeps the reply and drops the card for the rest of that connection’s life — an answer without a status line beats a status line without an answer.

“Control Center needs an app configuration token to edit the bot”

Section titled ““Control Center needs an app configuration token to edit the bot””

The Customise bot row is disabled because the connection has no app configuration token. (On the shared app there is no Customise bot row at all: the bot is the shared app’s.) This is expected for an app made by hand or through Create in Slack — Slack never told Control Center which app it is. Generate a token pair on api.slack.com/apps and reconnect with the refresh token filled in.

Slack caps a single message at 40,000 characters, so the bridge truncates at 39,000 and appends a pointer to Control Center — a shortened reply beats one Slack rejects outright. The full text is always in the space transcript.