Skip to content
CortexDocs

Connect Slack to Cortex

Capture channel messages with bot and app-level tokens.

Workplace connections

Slack

Content and access

Captured public-channel content is available to organization-wide Search. Direct messages and private-channel messages are excluded from that Search scope.

Before you begin

Use Cortex admin access and organization-wide connection requirements, plus these source-specific permissions:

Required

  • Slack app permissions

    Have permission to create and install a Slack app in the workspace.

Set up Slack

Stage 1: configure the Slack app in Slack

Create a Slack app for the workspace. Under OAuth & Permissions, add these Bot Token Scopes:

text
channels:history
channels:read
groups:read
im:read
mpim:read
users:read
users:read.email

Add all seven scopes so Cortex can list available channels. Cortex does not read direct messages.

Slack's live message search API accepts a user token only. Add these User Token Scopes if your deployment uses live Slack message search:

text
search:read
users:read.email

Then finish the Slack app:

  1. Enable Socket Mode.
  2. Enable Event Subscriptions and subscribe to the message.channels and message.groups bot events.
  3. Create an app-level token with the connections:write scope.
  4. Install the app to the workspace. If you change scopes after installing, reinstall it.
  5. Copy the bot token (xoxb-…), the app-level token (xapp-…), and the user token (xoxp-…) if you configured one.

Stage 2: connect Slack to Cortex

  1. In Cortex, open Organization → Apps and add Slack.
  2. Enter the bot token in Bot token and the app-level token in App-level token (optional). Add the search user token under Search user token (optional) if you created one.
  3. Select Test & preview and confirm the expected Slack workspace.
  4. Select Configure channels, review the channels Cortex found, and turn Ingest off for any channel Cortex should not use.

For channel capture, enter Bot token (xoxb-…) and App-level token (optional) (xapp-…) together. Despite its label, the app-level token is required for this Socket Mode connection. Without it, verification expects a search-only user token (xoxp-…) in the first field and rejects a bot token.

The search user token is optional and supports live Slack message search. Organization-wide Cortex Search reads captured public-channel content, so channel capture and those Search results work with the bot and app-level tokens.

What Search returns

Organization-wide Search returns public-channel content. Direct messages and private-channel messages are not shown in organization-wide Search.

In Slack channels, the Ingest column shows whether channel capture is enabled. Turning it off hides that channel from Search and Ask.

Manage this connection

  • Revoke or Delete stops token use. Remove the Slack app under the workspace's Manage apps.
  • Captured messages stay under your organization's retention terms. Contact Chaos Labs to purge them.

See the shared connection management guide for credential updates, stored token fields, and Cortex connection controls.