Skip to main content
Slack Logo
Slack

Team communication and messaging platform

✅ Ready📖 Documentation Available

​
Overview

The Slack connector syncs conversations from Slack — channels, messages, thread replies, shared files, and shared links — into PipesHub so they become searchable and available to agents. Slack ships as two separate connectors. Pick the one that matches how you want data brought in:
Both connectors can run side by side. The team connector gives the organization shared channel history; the individual connector adds each user’s DMs and private conversations, visible only to them.

​
What gets synced

Messages posted close together are grouped into short conversational bursts before indexing, so a back-and-forth exchange is retrieved as one coherent piece of context rather than isolated one-liners.

​
Configuration Guide

​
Overview

The Slack Workspace connector syncs public and private channels for your entire organization using a Slack app installed in your workspace. It authenticates with a Bot User OAuth Token, so there is no per-user sign-in.

​
Prerequisites

  • Permission to create and install a Slack app in your workspace (a workspace owner or admin may need to approve the installation).
  • PipesHub administrator access to Workspace Settings → Connectors.

​
Authentication

The connector uses a Bot Access Token (xoxb-…). You create a Slack app, grant it bot scopes, install it into your workspace, and paste the resulting token into PipesHub.

​
How to configure and enable the Slack Workspace connector

​
Step 1: Create a Slack app

  1. Go to the Slack API app dashboard and sign in.
  2. Click Create New App.
Slack API — Your Apps page with the Create New App button

​
Step 2: Start from a blank app

In the Create new app dialog, under Or start your own way, choose Blank app, then click Continue.
Slack — Create new app dialog with Blank app selected

​
Step 3: Name the app and pick the workspace

Enter an App name (for example slack-app), select the Workspace you want to sync, and click Create.
Slack — Create from scratch dialog with app name and workspace
The workspace cannot be changed later. Create the app in the workspace whose content you want PipesHub to index.

​
Step 4: Add Bot Token Scopes

  1. In the left sidebar, open OAuth & Permissions.
  2. Scroll to Scopes → Bot Token Scopes and click Add an OAuth Scope.
  3. Add every scope below:
Slack — Bot Token Scopes list
What each group of scopes is used for:
  • channels:* / groups:* — read public and private channel metadata and message history
  • channels:join — lets the bot join public channels on its own, so you don’t have to invite it to each one
  • im:* / mpim:* — read DM and group-DM metadata
  • users:read, users:read.email, users.profile:read — map Slack users to PipesHub accounts by email, and resolve @mentions to names
  • files:read — fetch files shared in messages
  • usergroups:read, usergroups.users:read — sync Slack user groups and their members

​
Step 5: Install the app to your workspace

Still on OAuth & Permissions, scroll to OAuth Tokens and click Install to <your workspace>.
Slack — OAuth & Permissions page with the Install to workspace button

​
Step 6: Review and allow the requested permissions

Confirm the workspace, review the requested permissions, and click Allow.
Slack — Review app permissions and allow installation
If your workspace requires admin approval for apps, the request is sent to a workspace owner. Installation finishes once they approve it.

​
Step 7: Copy the Bot User OAuth Token

Back on OAuth & Permissions, copy the Bot User OAuth Token — it starts with xoxb-.
Slack — Bot User OAuth Token under OAuth Tokens
Treat this token like a password. Anyone holding it can read the Slack content the app has access to. If it leaks, use Regenerate in Slack and update the connector.

​
Step 8: Configure the connector in PipesHub

  1. Navigate to Workspace Settings → under Workspace in the sidebar → Connectors.
Go to Workspace Settings
  1. Find the Slack Workspace connector and click + Setup.
  2. On the Authenticate Instance tab:
    • Enter an Instance name (for example Slack Workspace).
    • Paste the Bot Access Token from Step 7.
    • Click Next →.
PipesHub — Slack Workspace Configuration, Authenticate Instance tab with Bot Access Token

​
Step 9: Configure records and save

On the Configure Records tab, choose your Sync Strategy (Scheduled or Manual) and adjust the sync and indexing filters. See Connector Settings for what each filter does. Click Save Configuration.
PipesHub — Slack Workspace Configure Records tab with sync settings

​
Step 10: Start syncing

Once PipesHub confirms the instance is ready, you can start the sync immediately or start it later from the instance card.
PipesHub — Slack Workspace sync filters and indexing filters

​
Channel access for the bot

  • Public channels — the bot joins them on its own thanks to the channels:join scope, so no manual action is needed.
  • Private channels — Slack never grants an app access automatically. Invite the bot from inside each private channel you want synced:
Replace slack-app with the name you gave the app in Step 3.
DMs and group DMs are not synced by the team connector, even though the bot holds im:* and mpim:* scopes. Use the Individual Setup if you need personal conversations indexed.

​
Overview

The Slack connector syncs your own Slack view — public and private channels you are a member of, your direct messages, and your group DMs. Records synced this way are visible only to you in PipesHub.

​
Prerequisites

  • Permission to create a Slack app in your workspace (some workspaces require admin approval before an app can be installed).
  • A PipesHub account whose email matches the Slack account you will authorize with.

​
Authentication

This connector uses OAuth 2.0 with a user token (xoxp-…). You create a Slack app, register PipesHub’s callback URL, request user token scopes, then sign in from PipesHub to authorize it.
If an administrator has already registered a Slack OAuth app in PipesHub, you can select that saved app on the configuration screen and skip Steps 2 to 7 — go straight to authorizing.

​
How to configure and enable the Slack connector

​
Step 1: Copy the Redirect/Callback URL from PipesHub

  1. Navigate to Workspace Settings → under Personal in the sidebar → Your Connectors.
Go to Workspace Settings
  1. You will see the list of connectors available for Individual Setup.
Personal connectors list
  1. Find Slack, click + Setup, and on the Authenticate Instance tab set the Authentication method to OAuth 2.0.
  2. Copy the Redirect/Callback URL shown on that screen — you will paste it into Slack in Step 5.
PipesHub — Slack Configuration showing the Redirect/Callback URL and OAuth credentials fields
The URL follows the pattern https://your-frontend-dns/connectors/oauth/callback/Slack. Always copy the exact value from your own instance rather than typing it from memory.

​
Step 2: Create a Slack app

Go to the Slack API app dashboard, click Create New App, choose Blank app, then give the app a name (for example slack-personal-app) and select your workspace.
Slack API — Your Apps page with the Create New App button
Slack — Create from scratch dialog with app name and workspace

​
Step 3: Add the Redirect URL in Slack

  1. In the left sidebar, open OAuth & Permissions.
  2. Under Redirect URLs, click Add New Redirect URL and paste the URL you copied in Step 1.
  3. Click Add, then Save URLs.
Slack — Redirect URLs list with the PipesHub callback URL added
The redirect URL must match PipesHub’s value exactly — scheme, host, port, and path. A mismatch produces a bad_redirect_uri error during authorization.
Planning to use the Slack toolset as well? It has its own callback path (.../toolsets/oauth/callback/Slack). Add that URL here too so both can authorize against the same Slack app.

​
Step 4: Add User Token Scopes

On the same OAuth & Permissions page, scroll to Scopes → User Token Scopes and add every scope below.
Slack — User Token Scopes list
Add these under User Token Scopes, not Bot Token Scopes. The individual connector needs a user token (xoxp-…) to see your private channels and DMs; a bot token cannot access them.

​
Step 5: Install the app to your workspace

Scroll to OAuth Tokens, click Install to <your workspace>, and click Allow on the permission screen. This makes the app available for the OAuth sign-in you’ll run from PipesHub.
Slack — Review app permissions and allow installation

​
Step 6: Copy the Client ID and Client Secret

Open Settings → Basic Information and, under App Credentials, copy the Client ID and the Client Secret (click Show to reveal it).
Slack — Basic Information page with App Credentials

​
Step 7: Enter the credentials in PipesHub

Return to the Slack Configuration dialog and fill in:Confirm the Redirect/Callback URL still matches what you added in Slack, then click Next →.
PipesHub — Slack Configuration with OAuth app name and client credentials

​
Step 8: Authorize with Slack

On the Authorize tab, click Authenticate Slack to Proceed. Sign in to Slack and click Allow on the consent screen. When authorization succeeds, click Continue to configuration →.
PipesHub — Slack Configuration Authorize tab
Important: Authorize with the same email address as your PipesHub account. Using a different Slack account causes permission issues, and the sync stops early if your Slack email cannot be resolved.

​
Step 9: Configure records and save

On Configure Records, set your Sync Strategy and adjust the sync and indexing filters — including whether direct messages and group direct messages are indexed. See Connector Settings for details. Click Save Configuration, then start the sync now or later.

​
Sync Settings

Sync settings control how the connector pulls data from Slack.Sync Strategy:
  • Scheduled — the connector syncs automatically at the configured interval.
  • Manual — the connector syncs only when the sync is triggered from the connector settings page.
Sync Interval: How often a scheduled sync runs (default: 60 minutes).

​
Sync Filters

Sync filters control which conversations are fetched from Slack. Anything excluded here is never fetched, so it never becomes a record.

​
Channel

Include or exclude specific channels. The list is populated from your Slack workspace, so you can pick channels by name and use either an is any of (include) or is none of (exclude) operator.

​
Channel Types

Filter by conversation type.
  • Slack Workspace (Team): public_channel and private_channel. DMs and group DMs are not synced by the team connector.
  • Slack (Individual): public channel, private channel, Direct Messages, and Group Direct Messages.

​
Sync Messages From

How far back to reach on the initial sync — for example Last 30 Days (the default), or Is After with a specific date. Later syncs are incremental and pick up from where the last successful run stopped, so this window only applies the first time a channel is synced.
A wider window means a longer first sync. Start narrow if your workspace has years of history, then widen it later if you need more.

​
Enable Manual Indexing

When enabled, records are synced but not indexed automatically. They won’t appear in search results until you index them explicitly from the All Records section — go to a record, click the 3 dots → Start Indexing.

​
Indexing Filters

Indexing filters control which synced records are made searchable. Unlike sync filters, they don’t stop content from being fetched — the records still exist in PipesHub, but their indexing status is set to Manual Indexing and they can be indexed later from All Records.

​
Index Messages

When disabled, synced channel messages are not indexed for search by default.

​
Index Threads

When disabled, thread replies are not indexed for search by default.

​
Index Bot Messages

Slack Workspace (Team) only. Controls messages posted by bots and apps. When disabled, standalone bot messages — and threads whose parent message was posted by a bot — are skipped.

​
Index Direct Messages

Slack (Individual) only. When disabled, 1:1 direct messages are not indexed for search by default.

​
Index Group Direct Messages

Slack (Individual) only. When disabled, group direct messages are not indexed for search by default.

​
Index Files

When disabled, files shared in messages are not indexed for search by default.When disabled, links shared in messages are not indexed for search by default.

​
Data sync behavior

​
Initial sync

Runs in phases: users (and, for the team connector, user groups) → channels → messages, files, and links per channel → thread replies. How long it takes depends on how many channels you sync and how far back Sync Messages From reaches.

​
Incremental sync

Each channel keeps its own checkpoint, so later runs fetch only messages posted since that channel’s last successful sync. Threads are checked separately, so replies added to an older conversation are still picked up.

​
What incremental sync does not catch

Slack’s history API returns messages by the time they were created, not the time they were last modified. Edits to a message older than the current sync window aren’t detected — the connector sees new messages and new thread replies, not retroactive edits.

​
Rate limits

Slack rate-limits its API per method. The connector paces its own calls to stay under those limits, which is why large workspaces sync gradually rather than all at once.

​
Troubleshooting

​
Common issues

not_in_channel / a private channel isn’t syncing (Team)
  • Slack apps have no automatic access to private channels. Invite the bot from inside the channel with /invite @your-app-name, then run the sync again.
missing_scope
  • A required scope wasn’t granted. Add it in OAuth & Permissions, then reinstall the app — scope changes only take effect after reinstalling.
bad_redirect_uri or redirect_uri_mismatch (Individual)
  • The Redirect URL in Slack must match the one in PipesHub exactly, including scheme, host, port, and path.
invalid_auth / token_revoked / token_expired
  • Signed in with Slack, with token rotation on: on invalid_auth or token_expired, PipesHub renews the token and retries the call once. You still see these errors if Slack refuses the retry too. You also see invalid_auth without a new renewal if the token was renewed less than a minute earlier, because a newer token wouldn’t help. If they keep appearing, re-run authorization from the Authorize tab. See Token rotation below.
  • token_expired on a pasted token: the token comes from a Slack app with token rotation on, and it has reached its 12-hour expiry. A new token from the same app will expire again, so follow Token rotation below: use an app with rotation left off, or connect the Individual connector with Slack sign-in.
  • token_revoked, or invalid_auth on a pasted token: the token was regenerated or the app was uninstalled. For the Workspace connector, paste the new Bot User OAuth Token. For the Individual connector, paste the new user token if you use the API token option, or re-run authorization from the Authorize tab if you signed in with Slack.
“Invalid Slack token format”
  • PipesHub accepts bot tokens (xoxb-…) and user tokens (xoxp-…), and, for apps with token rotation turned on, the rotating forms xoxe.xoxb-… and xoxe.xoxp-…. A token that starts with just xoxe- is a refresh token, which can’t call Slack; paste the access token from OAuth & Permissions instead.
Token rotationWith token rotation turned on, Slack’s access tokens expire after about 12 hours. Each one comes with a refresh token that works once. What happens next depends on how the connector got its token:
  • Signed in with Slack (Individual connector, OAuth): rotation is supported. PipesHub renews the token before it expires and saves the new refresh token each time, so you don’t need to do anything. If a renewal is missed, the connector renews the token on the next call to Slack and retries that call once.
  • Pasted token (Workspace connector, or the API token option of the Individual connector): a pasted token has no refresh token, so PipesHub can’t renew it, and syncing stops about 12 hours after you paste it. The connector logs that the pasted token has expired. Use a Slack app with token rotation left off for pasted tokens. Slack doesn’t let an app turn rotation off once it’s on, so if yours has it on, create a new app without it, or connect the Individual connector with Slack sign-in instead.
“Slack no longer accepts PipesHub’s saved sign-in” in the connector logs means Slack refused the refresh token, usually because the app was reinstalled or removed, or the sign-in was revoked. Renewing again can’t fix that, so PipesHub stops trying. Re-run authorization from the connector’s Authorize tab to reconnect Slack. After a few refused renewals, the connector is also marked as needing to be reconnected.
Only a bot token was found (Individual)
  • The individual connector needs a user token (xoxp-…). Confirm the scopes were added under User Token Scopes, not Bot Token Scopes, and authorize again.
Users are missing from the sync (Team)
  • Members without an email address on their Slack profile are skipped, because PipesHub matches people by email. Bots are cached for mention resolution but are not created as users.
Nothing synced beyond a certain date
  • Check Sync Messages From. On a first sync, anything older than that window is deliberately skipped.

​
FAQ

Use Slack Workspace when an administrator wants channel history available across the organization, with permissions mirroring Slack’s own channel membership. Use Slack (Individual) when a user wants their own view indexed, including DMs and group DMs, visible only to them.They aren’t mutually exclusive — running both gives shared channel history plus personal conversations.
Example: Use the Slack Connector to search what a team decided last quarter. Use the Slack Toolset to let an agent post the answer back into a channel.
No. The connector is read-only — it reads channels, messages, files, and links. The only write-like action is the bot joining public channels so it can read their history, which requires the channels:join scope.
There are three common causes:
  1. Email mismatch — the email used during authentication doesn’t match your PipesHub account email, which causes permission issues on synced data.
    • Fix: Reconfigure the connector and authenticate with the same email as your PipesHub account.
  2. Records show in “All Records” but not in search — indexing hasn’t run for those records.
    • Fix: Check whether Enable Manual Indexing is on, or whether the relevant indexing filter (messages, threads, files, links) is disabled. Index the records manually from All Records if needed.
  3. Data not yet synced or indexed — the connector is still working through the initial sync.
    • Fix: Go to Settings → Connectors, check the sync status, and wait for indexing to complete.

​
Ready to get started?

Connect Slack to PipesHub for unified search across your conversations. Follow the configuration guide above for your setup type (Team or Individual), or reach out to our support team if you need assistance.