Skip to main content

​
June 2025 Update

Slack has changed their Terms of Service, preventing users from indexing their data (source: Slack). As a result, the only way to add Slack information into Onyx is by using the search APIs that Slack provides. These APIs are significantly slower and lower quality than the previous index-based approach. Your data is your data — if you care about higher quality Slack search then please talk to your customer success representative and make it clear that this change reduces the value you get out of Slack. If you have any questions, please reach out to [email protected] or send us a message in Slack.

​
Setting up

​
Authorization

1

Prerequisite

You must be an admin of the Slack workspace to set up the connector.
2

Open Slack apps

Navigate and sign in to https://api.slack.com/apps.
3

Create new app

Click the Create New App button in the top right. Select From an app manifest option. Select the relevant workspace from the dropdown and click Next.Slack app creation flow with manifest option selected
4

Paste manifest

Select the “YAML” tab, paste the following manifest into the text box, and click Next:
display_information:
  name: Onyx Search Assistant
  description: Search your Slack data as yourself
  background_color: "#4A154B"
oauth_config:
  redirect_urls:
    - <YOUR_ONYX_DOMAIN>/federated/oauth/callback
  scopes:
    user:
      - channels:read
      - groups:read
      - im:read
      - mpim:read
      - search:read
      - channels:history
      - groups:history
      - im:history
      - mpim:history
      - users:read
settings:
  org_deploy_enabled: false
  socket_mode_enabled: false
  token_rotation_enabled: false
For Onyx Cloud, the redirect_urls value should be https://cloud.onyx.app/federated/oauth/callback.
We do not currently support token rotation, so token_rotation_enabled: false is necessary.
1

Create app

Click the Create button.
2

Open Basic Information

In the app page, navigate to the Basic Information tab under the Settings header.
3

Copy client credentials

Copy the Client ID and Client Secret. Store those somewhere safe for the next step.
Slack Basic Information page with Client ID and Client Secret

​
Indexing

1

Open Slack connector

Navigate to the Connector Dashboard and select the Slack Connector.
2

Enter client credentials

Enter the Client ID and Client Secret from step 7.
3

Configure search scope

Configure the search scope for the federated connector. The following configuration options are available:Channel Selection:
  • Search All Channels: Enable to search all accessible channels. When enabled, the Channels field is disabled.
  • Channels: Specify which channels to search (only used if Search All Channels is disabled). Supports glob patterns (e.g., general, eng*, product-*).
  • Exclude Channels: Exclude specific channels from search. Supports glob patterns (e.g., secure-channel, private-*, customer*).
Message Types:
  • Include Direct Messages: Include user direct messages (1:1 DMs) in search results.
  • Include Group Direct Messages: Include multi-person direct messages (MPIMs) in search results.
  • Include Private Channels: Include private channels in search results (user must have access).
Search Parameters:
  • Default Search Days: Maximum number of days to search back (default: 30). Increasing this value may degrade answer quality.
  • Max Messages Per Query: Maximum number of messages to retrieve per search query (default: 25). Higher values provide more context but may be slower.
Once configured, click the Create/Update button.Onyx Slack Federated connector settings showing client credentials
4

Complete OAuth

Head back to the main Chat page and go through the OAuth flow!
Every user will need to go through this OAuth flow. The searchable content depends on:
  • The connector configuration settings (channels, DMs, private channels, etc.)
  • The OAuth scopes granted during setup
  • The user’s individual access permissions in Slack
If certain OAuth scopes are missing (e.g., mpim:read, im:history), the connector will gracefully continue searching other available channel types and log warnings about the missing scopes.
Slack OAuth consent screen for Onyx Search Assistant