Slack Integration

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) or by @mentioning the bot in public channels. When a user sends a message to the bot, it processes the query, creates a report in the application, and returns the result in a thread.

​

Capabilities

• Direct Messaging: Interact with the bot in a one-on-one DM conversation within Slack.
• Channel @Mentions: Mention the bot in any public channel to ask questions visible to the whole channel.
• Threaded Conversations: All bot replies appear in threads. Each new message starts a thread, and follow-up replies continue the same conversation.
• Thread = Report Mapping: Each Slack thread corresponds to a single report. Replies within a thread continue the existing report rather than creating new ones.
• Visual Feedback: The bot uses emoji reactions to indicate status:
  • 👀 (eyes) — Message received, processing in progress
  • ✅ (checkmark) — Response complete
• 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.
• Context-Aware Data Access: The bot queries different data sources based on the conversation context:
  • Channel mentions: Only public data sources are queried (responses are visible to everyone in the channel)
  • Private DMs: Both public and private data sources the user has access to are queried
• Rich Responses: Receive responses as text, images, or files directly in Slack.

---

​

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)
   • reactions:write (to send 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 add the following events:
   • message.im — Allows the bot to receive direct messages
   • app_mention — Allows the bot to respond when @mentioned in channels
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

You can interact with the bot in two ways: Option A: Direct Messages

1. Open a DM with the bot in Slack.
2. Send your query or command. The bot will add a 👀 reaction to indicate it’s processing.
3. The bot will reply in a thread with the response and replace the 👀 with a ✅ when complete.
4. Continue the conversation by replying in the thread — follow-up messages will extend the same report.

Option B: Channel @Mentions

1. In any public channel, @mention the bot followed by your question (e.g., “@BotName what were last month’s sales?”).
2. The bot will add a 👀 reaction and respond in a thread on your message.
3. Reply in the thread to continue the conversation.