Sync Slack Channel Messages into Brainfish

Use this guide to connect a Slack channel as an external data source and push its messages and threads into a Brainfish catalog.

Overview

To sync Slack content into Brainfish, your team will:

1. Create a Slack app with a bot user.
2. Grant the bot read access to the channel messages and threads you want to sync.
3. Install the app into your Slack workspace.
4. Invite the bot to each Slack channel that should be synced.
5. Fetch channel messages and thread replies from Slack.
6. Push the content into Brainfish using the catalog create and update API.

Step 1: Create the Slack App

1. Go to Slack API Apps.
2. Select Create New App.
3. Choose From an app manifest.
4. Select your Slack workspace.
5. Paste the YAML manifest below.
6. Review the configuration and create the app.

display_information:
  name: Brainfish Sync
  description: Sync selected Slack channel messages and threads into Brainfish
  background_color: "#2c2d30"

features:
  bot_user:
    display_name: Brainfish Sync
    always_online: false

oauth_config:
  scopes:
    bot:
      - channels:read
      - channels:history
      - groups:read
      - groups:history
      - users:read

settings:
  org_deploy_enabled: false
  socket_mode_enabled: false
  token_rotation_enabled: false

Step 2: Install the App

1. In the Slack app settings, open OAuth & Permissions.
2. Select Install to Workspace.
3. Approve the requested permissions.
4. Copy the Bot User OAuth Token.

The bot token starts with xoxb-. Store it securely and use it only from your server-side sync job.

Step 3: Invite the Bot to the Channel

The bot must be a member of every Slack channel you want to sync. In each target channel, run:

/invite @Brainfish Sync

If you used a different app name, replace Brainfish Sync with the name of your Slack app.

Step 4: Fetch Slack Messages and Threads

Use the Slack Web API from your server-side sync job.

For public channels, use:

• conversations.list to find channel IDs.
• conversations.history to fetch channel messages.
• conversations.replies to fetch thread replies.

For private channels, the same APIs apply, but the bot must be invited to the private channel first.

When exporting messages, include enough context for Brainfish to understand the content, such as:

• Channel name
• Message permalink
• Message timestamp
• Author display name, if available
• Message body
• Thread replies
• Any relevant dates or labels

Step 5: Create a Brainfish Catalog

Create one Brainfish catalog for the Slack channel source. Use the catalog create API with source set to external.

Example request body:

{
  "name": "Slack - Support Channel",
  "source": "external",
  "slug": "slack-support-channel",
  "configurations": {
    "sourceSystem": "slack",
    "syncType": "channel_messages"
  }
}

Store the returned catalog ID. You will use it when pushing Slack content into Brainfish.

Step 6: Push Messages into the Catalog

Use the catalog update API to push the complete set of Slack files for the catalog. Each file needs a stable url, a title, and the message or thread content.

Example request body:

{
  "files": [
    {
      "url": "slack://C0123456789/1715551200.000100",
      "title": "Support channel message - 2026-05-13 10:00",
      "content": "# Slack message\n\nChannel: #support\nAuthor: Jane Smith\nPosted: 2026-05-13 10:00 UTC\nPermalink: https://your-workspace.slack.com/archives/C0123456789/p1715551200000100\n\nCustomer asked how to reset their API key. The support team replied with the account settings steps."
    },
    {
      "url": "slack://C0123456789/1715551300.000200/thread",
      "title": "Support thread - API key rotation",
      "content": "# Slack thread\n\nChannel: #support\nStarted by: Alex Lee\nStarted: 2026-05-13 10:01 UTC\nPermalink: https://your-workspace.slack.com/archives/C0123456789/p1715551300000200\n\n## Original message\nHow do customers rotate an API key?\n\n## Replies\n- Sam: They can create a new key in Settings, update their integration, then revoke the old key.\n- Alex: Confirmed this should be documented under API keys."
    }
  ]
}

Use a stable url value for each Slack message or thread. Brainfish uses this value as the unique identifier for create and update behavior.

Sync Behavior

The catalog update API performs a full sync for the catalog:

• New files are created.
• Existing files with the same url are updated.
• Files that are no longer included in the update request are removed from the catalog.

Because omitted files are removed, each update should include the complete current set of Slack messages and threads you want Brainfish to retain for that catalog.

Recommended Formatting

For best results, format each Slack message or thread as Markdown. Include the original message, thread replies, author names, timestamps, and permalinks.

Use one file per standalone message or thread. For threaded conversations, keep the original message and its replies together in a single file so Brainfish can understand the full conversation context.

Security Notes

• Keep the Slack bot token secret.
• Do not expose the token in browser-side code.
• Only grant the Slack scopes required for the channels being synced.
• Remove sensitive Slack messages before syncing if they should not be available in Brainfish.
• Rotate the Slack bot token if it is accidentally exposed.

Troubleshooting

If no messages are being synced, check that:

• The Slack app is installed in the correct workspace.
• The bot has been invited to the target channel.
• The bot token starts with xoxb- and is being used server-side.
• The app has channels:history for public channels.
• The app has groups:history for private channels.
• The catalog update request includes at least one file with url, title, and content.