> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getomni.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Slack
> Connect Slack workspaces to Omni for unified search across messages, threads, and files
The Slack connector enables Omni to index and search content from your Slack workspace, including channel messages, threads, and text files.
## Overview
### What Gets Indexed
| Source | Content |
| ---------------- | --------------------------------------------------------------------- |
| Channel Messages | Messages from public and private channels (where bot is a member) |
| Threads | Full thread conversations with all replies |
| Direct Messages | 1:1 DMs and group DMs the bot is a participant in |
| Files | File attachments — text, PDFs, DOCX/PPTX/XLSX, images (via OCR), etc. |
### How It Works
1. A Slack bot is installed in your workspace with read-only permissions
2. The connector syncs messages from channels and DMs where the bot is a member
3. Messages are grouped by date and thread for efficient indexing
4. Permission inheritance ensures users only see content from channels and DMs they can access
5. On first sync, the connector indexes the last 2 years of history per conversation by default — see [Advanced configuration](#advanced-configuration) to tune
For direct messages, the bot can only see DMs and group DMs it has been explicitly invited to or messaged. Bot tokens cannot read DMs between two users — that's a Slack platform restriction, not an Omni one.
The connector uses read-only access. Omni cannot post messages or modify any content in your Slack workspace.
## Prerequisites
Before setting up the Slack connector, ensure you have:
* **Slack workspace admin access** to install apps
* **Omni deployment** with the Slack connector service running
## Setup
### Step 1: Create a Slack App
1. Go to [Slack API Apps](https://api.slack.com/apps)
2. Click **Create New App** → **From an app manifest**
3. Select your workspace and click **Next**
4. Choose **YAML** and paste the following manifest:
```yaml theme={null}
display_information:
name: Omni Search
description: Read-only bot for Omni search indexing
features:
bot_user:
display_name: Omni Search
always_online: false
oauth_config:
scopes:
bot:
- channels:history
- channels:join
- channels:read
- files:read
- groups:history
- groups:read
- im:history
- im:read
- mpim:history
- mpim:read
- usergroups:read
- users:read
- users:read.email
settings:
event_subscriptions:
bot_events:
- app_mention
- message.channels
- file_created
- file_deleted
- file_changed
org_deploy_enabled: false
socket_mode_enabled: true
token_rotation_enabled: false
```
5. Click **Next**, review the summary, and click **Create**
| Scope | Purpose |
| ------------------ | -------------------------------------------------------------------- |
| `channels:history` | Read message history from public channels |
| `channels:join` | Allow bot to join public channels for indexing |
| `channels:read` | View basic channel information |
| `files:read` | Download files attached to messages |
| `groups:history` | Read message history from private channels the bot has been added to |
| `groups:read` | View basic info for private channels the bot has been added to |
| `im:read` | List 1:1 DMs the bot is a participant in |
| `im:history` | Read messages from those 1:1 DMs |
| `mpim:read` | List group DMs the bot is a participant in |
| `mpim:history` | Read messages from those group DMs |
| `usergroups:read` | View user groups in the workspace |
| `users:read` | View user profiles for author information |
| `users:read.email` | View user email addresses for identity matching |
### Step 2: Install App to Workspace
1. Go to **OAuth & Permissions**
2. Click **Install to Workspace**
3. Review and authorize the permissions
4. Copy the **Bot User OAuth Token** (starts with `xoxb-`)
Keep your bot token secure. Anyone with access to this token can read messages from your Slack workspace.
### Step 3: Enable Real-Time Updates (Optional)
To receive near real-time indexing of new messages and files, enable Socket Mode:
1. Go to **Socket Mode** in your Slack app settings
2. Enable **Socket Mode**, and copy the **App Level Token** displayed
This step is optional. Without an app-level token, the connector still works using scheduled full and incremental syncs. Enabling Socket Mode adds near real-time indexing with up to \~10 minute delay.
### Step 4: Add Bot to Channels
During sync, the bot automatically joins all public channels. For private channels, you must manually add the bot:
1. Open the private channel you want to index in Slack
2. Click the channel name to open details
3. Go to **Integrations** tab
4. Click **Add apps**
5. Find and add **Omni Search**
Public channels are automatically indexed — the bot joins them during each sync. You only need to manually invite the bot to **private channels** you want indexed.
### Step 5: Connect in Omni
1. Navigate to **Settings** → **Integrations** in Omni
2. Find **Slack** and click **Connect**
3. Enter your Slack Client ID, Client Secret, Bot User OAuth Token, and optionally the App-Level Token for real-time updates
4. Click **Connect**
5. Click **Sync Now** to start the initial sync
Your Slack connector is now configured. Initial indexing may take a while depending on the amount of content in your channels.
## Managing the Integration
### Viewing Sync Status
Navigate to **Settings** → **Integrations** to view the sync status for each source directly on the list, including last sync time, number of indexed items, and any errors. Click **Configure** on a source for more details.
### Sync Modes
The Slack connector supports three sync modes:
| Mode | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------- |
| **Full** | Syncs all messages from all channels (used for initial sync) |
| **Incremental** | Syncs only new messages since last sync (used for updates) |
| **Real-Time** | Receives events via Socket Mode for near real-time indexing (up to \~10 min delay). Requires app-level token. |
After the initial full sync, the connector automatically performs incremental syncs to capture new messages. To enable real-time updates, provide the app-level token during setup (see Step 3).
### Adding More Channels
To index additional channels:
1. Add the Omni bot to the new channel (see Step 4)
2. The next sync will automatically include the new channel
### Removing the Integration
1. Navigate to **Settings** → **Integrations**
2. Click **Configure** against the Slack source
3. Click **Delete Permanently**
4. Optionally, uninstall the Omni app from your Slack workspace
## Advanced configuration
The Slack connector reads a few optional environment variables at startup. These apply to the connector container globally — set them in your deployment's env file or task definition.
| Variable | Default | Description |
| -------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SLACK_MAX_AGE_DAYS` | `730` (2 years) | First-sync history horizon, in days. Channels and DMs are backfilled at most this far back. Subsequent incremental syncs only fetch messages newer than the last seen one and ignore this bound. Increase if you have a paid Slack plan and want full historical coverage; decrease to keep the initial sync fast on busy workspaces. |
## Troubleshooting
Common causes:
* Bot is not a member of the channel
* Sync has not completed yet
* Channel permissions don't allow the user to see results
**Solution**: Add the bot to the channel and trigger a manual sync.
The token may be expired or revoked.
**Solution**:
1. Go to your Slack app settings
2. Regenerate the Bot User OAuth Token
3. Update the token in Omni via **Settings** → **Integrations** → **Slack**
4. Restart the Slack connector service
Slack has API rate limits. The connector handles these automatically with backoff.
**Solution**: Wait for the connector to retry. For large workspaces, initial sync may take longer due to rate limits.
The bot must be explicitly invited to private channels.
**Solution**: Open the private channel, go to **Integrations** → **Add apps**, and add the Omni bot.
Most file types — text, PDFs, Office docs (DOCX/PPTX/XLSX), and images (via OCR) — are extracted automatically. Audio/video and other unsupported binary formats are skipped silently.
If a specific file is missing, common causes:
* The bot lost access to the channel where the file was shared
* The file is on a Slack plan with retention limits and is older than the workspace's retention window
* Extraction failed for that specific file (check connector logs)
## Security Considerations
* **Read-only access**: The bot only has read permissions
* **Channel-based permissions**: Users only see messages from channels they can access in Slack
* **Token security**: Bot tokens should be treated like passwords
* **Audit logging**: Monitor bot activity in Slack's audit logs
## What's Next
Learn how to search across Slack messages
Ask questions about your Slack conversations
Connect additional data sources