Connect Slack

Slack is optional. When it is enabled, Cengrid’s Slack plugin runs inside core and opens an outbound Socket Mode connection to Slack, so you do not need a public URL for Slack events.

Three different Slack apps

Cengrid can use up to three separate Slack apps. They are not interchangeable.

App	Purpose	Needed when
Bot app	Receives conversations and replies in channels and DMs	You want Cengrid in Slack. This page.
SSO app	“Sign in with Slack” for the web UI. Named <botName> SSO.	The portal uses Slack OpenID instead of the built-in email sign-in. See Slack sign-in.
Account connector app	Lets each person authorise Cengrid to act as their own Slack account	You want the agent to search or post as a person. See Slack account connection.

Set up the bot

You need permission to install apps in your Slack workspace. Slack Connect and a paid plan are not required, though the Slack Agents top-bar pane needs a paid plan.

1. Get the manifest. Open Admin → Onboarding → Slack, choose Configure, and in the drawer choose Create the Slack app →. This opens Slack with the manifest pre-filled, using your bot name from Branding.

   From the command line, cengrid outputs prints the same creation link, and cengrid slack render regenerates slack-app-manifest.yml after you change botName or orgId.

2. Create the app. In Slack, create a new app from a manifest, pick your workspace and create it.

3. Install it to the workspace from OAuth & Permissions and copy the Bot User OAuth Token. It starts with xoxb-.

4. Create an app-level token. Under Basic Information → App-Level Tokens, generate a token with the connections:write scope and copy it. It starts with xapp-. The manifest turns on Socket Mode but Slack cannot create this token for you, so this step is always manual.

5. Give Cengrid both tokens, in one of two ways:

   Admin console (recommended)

   In Admin → Onboarding → Slack, choose Configure and paste both tokens. Cengrid checks the xoxb- and xapp- prefixes, calls Slack to validate them, and confirms both tokens belong to the same Slack app before saving. Tokens are stored encrypted, and the running instance picks up changes within about five seconds with no restart.

   Environment secrets

   Put SLACK_BOT_TOKEN and SLACK_APP_TOKEN in your deployment’s .env, then run cengrid secrets push. When tokens come from the environment the admin card is read-only.

6. Verify. Invite the bot to a channel, add that channel as a room, and mention the bot. Core logs [slack-plugin] connected as @… in team … when the connection is up.

If both are present, a token saved in the admin console wins over the environment. If you used the admin card and later Disconnect, Slack stays off even if environment tokens exist.

One running core per Slack app

Socket Mode load-balances events across every connected client of the same app. Give each deployment, and each developer’s test instance, its own Slack app.

Rooms

A Slack channel only becomes a room when an administrator configures it. Rooms are configured, not discovered.

1. Invite the bot to the channel in Slack.
2. Open Admin → Rooms → Add room → Slack and pick the channel from the list of channels the bot belongs to.
3. Choose a team for the room, creating one if needed. The room’s capabilities and settings come from that team.

A configured room has the id room:slack:<channelId>. Cengrid posts a welcome message and a pinned header when the room is configured, not when the bot joins. If someone mentions the bot in a channel that has not been added, the bot replies privately: it is not set up there yet and an admin should add it under Admin → Rooms. See teams and rooms.

How the bot behaves

• Direct messages need no setup. They run in the sender’s personal scope, one continuous session per DM, shared with the web app and Google Chat DMs.
• Channels: mention the bot to start a thread. The bot replies in that thread, with one session per thread. After a real mention, later replies in the thread need no second mention. The bot decides whether to answer and may stay silent. A new top-level message still needs a mention.
• Stop: a bare stop after the bot mention stops the run, and plan checklists show a Stop button.
• Approvals: when a command needs approval, the bot posts Allow once and Deny buttons, plus Allow session and Allow always unless Governance → Security → Approval grant modes disables them. Only the person who requested the command can answer.
• Personal agent handoff: a request to run with another person’s setup arrives as a DM with Run with my setup and Decline.
• Shared and external channels: in Slack Connect channels, or channels with a guest or external member, the bot stays quiet in the channel and replies privately. Whether external participants are admitted is an admin setting.
• Group DMs are not supported and are ignored.
• Conversation log: configured rooms record every message by default. Admins can turn log sync off per room.

Permissions the manifest requests

The generated manifest requests these bot scopes:

Scope	Used for
app_mentions:read	Mentions
chat:write, chat:write.customize	Posting and editing replies, with the bot’s display name and icon
im:history, im:read, im:write	Direct messages and opening DMs for approvals
channels:history, groups:history	Reading thread and room messages
channels:read, groups:read	Listing channels and members
users:read, users:read.email	The people directory and email-based identity
files:read, files:write	Reading attachments and uploading files
reactions:read, reactions:write	Reactions
pins:read, pins:write	The pinned room header
assistant:write	The Slack Agents top-bar pane
channels:manage, groups:write, emoji:read	Included in the generated manifest

and subscribes to these events: app_mention, message.im, message.channels, message.groups, member_joined_channel, member_left_channel, channel_created, channel_rename, channel_unarchive, reaction_added, reaction_removed, assistant_thread_started and assistant_thread_context_changed. Interactivity is on, for approval buttons. There are no slash commands.

Identity

By default Cengrid maps Slack people to its own people by email. It needs the users:read.email scope for that. A Slack human with no visible email is treated as a guest and fails closed. The directory refreshes every 15 minutes.

SLACK_IDENTITY_EMAIL controls this: 1 keys people by email, 0 keys them by Slack id, and unset probes automatically. If the log warns users:read.email scope missing?, add the scope or set SLACK_IDENTITY_EMAIL=1.

Using the same lower-cased email for Slack and for web sign-in is what makes both resolve to the same person.

Slack sign-in

By default the web UI signs people in with the built-in email broker, so you do not need Slack SSO. To use Sign in with Slack instead, point the portal at Slack’s OpenID endpoints, drop "auth" from services, and create the SSO app:

1. Run cengrid slack render. It writes slack-sso-manifest.yml only when the portal’s OIDC endpoints are on slack.com. Create an app from it. The manifest requests the user scopes openid, profile and email, and the redirect <publicUrl>/auth/callback.
2. Set OIDC_CLIENT_ID and OIDC_CLIENT_SECRET from the SSO app’s Basic Information page, then run cengrid secrets push.
3. Set one trust boundary: PORTAL_EXPECTED_TEAM_ID (your Slack workspace id), OIDC_ALLOWED_EMAIL_DOMAIN, or OIDC_ALLOWED_EMAILS.

The redirect must be exactly <publicUrl>/auth/callback. SSO does not require the bot, and the bot does not require SSO.

Slack account connection

This is separate from the bot. It is a per-person OAuth connector that lets the agent act as that person in Slack, for example to search messages. An administrator creates a Slack app from scratch for it, enters its client id and secret under Connections → Available → Slack → Configure, in the Organization setup section, and people then connect from their Keychain. The redirect is <publicUrl>/v1/connectors/oauth/slack/callback, not /auth/callback. It uses user token scopes for reading and posting in channels, DMs and canvases, and for search.

Update or troubleshoot

• After a scope or event change, update the app from the new manifest in Slack and reinstall it. Without reinstalling, new capabilities such as reactions or thread replies are silently missing.
• cengrid doctor checks SLACK_BOT_TOKEN and SLACK_APP_TOKEN against Slack when they are in your deployment secrets or .env, and compares the app’s granted scopes with slack-app-manifest.yml. It reports missing scopes and tells you to update from the manifest and reinstall. Tokens saved only through the admin card are not checked, and with neither variable set it reports Slack setup as deferred to the admin page.
• “bot token and app token belong to different Slack apps” means you pasted tokens from two different apps.
• Rotating tokens: token rotation is off in the manifest. To rotate, paste new tokens with Replace tokens on the admin card, or update the environment secret.
• Files: only Slack-hosted files are ingested; remote files are refused.