​
Slack Integration Guide

This guide provides instructions on how to connect your workspace to Slack. The integration allows you and your team to interact with our platform directly from Slack, enabling a seamless workflow for running queries and accessing information from your connected data sources.

​
Overview

The Slack integration installs a bot into your Slack workspace, allowing users to interact with our platform directly from Slack. To ensure security, each Slack user must first authenticate and link their account to their application account. This one-time verification step guarantees that all interactions are secure and correctly associated with the right user and their permissions within the application. Once authenticated, users can interact with the bot through Direct Messages (DMs). When a user sends a message to the bot, it processes the query, creates a report in the application, and returns the result directly in the DM.

​
Capabilities

  • Direct Messaging: Interact with the bot in a one-on-one conversation within Slack.
  • Secure User Authentication: Each user’s Slack account is mapped to their application account, ensuring all actions are authorized.
  • Natural Language Queries: Ask questions and give commands in plain English.
  • Automatic Report Generation: Every conversation initiated via Slack automatically creates a corresponding report in your application account.
  • Access to Data Sources: The bot utilizes the active data sources configured in your organization to provide contextual and accurate answers.
  • Rich Responses: Receive responses as text, images, or even files directly in your Slack DM.

​
How to Integrate

Follow these steps to configure the integration. This process requires you to have administrative permissions in both our application (to manage integrations) and your Slack workspace (to create and install apps).

​
Step 1: Create a Slack App

  1. Navigate to the Slack API dashboard.
  2. Click Create New App and select From scratch.
  3. Enter an App Name (e.g., “Company AI Assistant”) and select the Workspace where you want to install it.
  4. Click Create App.

​
Step 2: Configure Permissions (OAuth Scopes)

For the bot to function correctly, you must grant it specific permissions.
  1. In your Slack App’s settings, go to the OAuth & Permissions page from the sidebar.
  2. Scroll down to the Bot Token Scopes section.
  3. Click Add an OAuth Scope and add the following scopes one by one:
    • app_mentions:read (to view messages that directly mention the bot)
    • channels:read (to view basic information about public channels)
    • chat:write (to send messages as the bot)
    • files:read (to view files shared in conversations)
    • files:write (to upload, edit, and delete files)
    • im:history (to view message history in DMs)
    • im:read (to view basic information about DMs)
    • im:write (to start DMs with people)
    • reactions:read (to view emoji reactions in conversations)
    • users:read (to view people in the workspace)
    • users:read.email (to view user email addresses)

​
Step 3: Install the App and Get the Bot Token

  1. At the top of the OAuth & Permissions page, click Install to Workspace.
  2. Follow the on-screen prompts to authorize the application in your selected workspace.
  3. Once installed, you will be redirected back to the OAuth & Permissions page. Copy the Bot User OAuth Token that starts with xoxb-. This is your Bot Token.

​
Step 4: Enable Event Subscriptions

This step allows your bot to listen for messages sent to it.
  1. In your Slack App’s settings, go to the Event Subscriptions page from the sidebar.
  2. Toggle the switch to On.
  3. In the Request URL field, you will need to enter the webhook URL for our application. It is your application’s base URL followed by /api/settings/integrations/slack/webhook.
    • Example: https://YOUR-BOW-URL.com/api/settings/integrations/slack/webhook
  4. After you enter the URL, Slack will attempt to verify it. A green “Verified” checkmark will appear if successful.
  5. Scroll down to the Subscribe to bot events section.
  6. Click Add Bot User Event and select message.im. This allows the bot to receive direct messages.
  7. Click Save Changes.

​
Step 5: Get the Signing Secret

  1. Go to the Basic Information page from the sidebar.
  2. Scroll down to the App Credentials section.
  3. Copy the Signing Secret by clicking Show.

​
Step 6: Connect in the Application

  1. In our application, navigate to the Settings > Integrations page.
  2. Click Integrate (or Settings) for the Slack integration.
  3. A modal will appear. Paste the Bot Token and Signing Secret you copied from the Slack App settings into the respective fields.
  4. Click Connect. If successful, the modal will close, and the UI will show that Slack is connected.

​
How to Use

Once the integration is active, users in your organization can start interacting with the bot.

​
Step 1: User Account Verification

Before a user can interact with the bot, they must link their Slack account to their application account. This is a one-time process.
  1. In Slack, find the bot you installed. You can find it in the “Apps” section of your Slack sidebar.
  2. Send any Direct Message to the bot (e.g., “Hello”).
  3. The bot will respond with a unique verification link. Click the button or link in the message.
  4. You will be redirected to a verification page in our application. Once verified, you can close the page.

​
Step 2: Chat with the Bot

  1. Open a DM with the bot in Slack.
  2. Send your query or command as a message. The bot will reply with “Thinking…” to acknowledge receipt.
  3. Once processed, the bot will send the complete response. Your conversation history is automatically saved as a new report in your application account.