> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildbetter.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Slack Integration

> Connect BuildBetter with Slack to share call summaries and create signals from customer conversations

<Tip>
  **Quick Reference:**

  * Want **automatic Signal creation** from a channel? → Run `/bb connect` and select "Import Conversations"
  * Want to **push call summaries** to a channel? → Run `/bb connect` and select "Push Summaries"
  * Want to **track Topics** from a channel? → Run `/bb connect` and select "Topics Source"
  * Want to **make a channel available to workflows**? → Run `/bb connect` and select "Workflows"
  * Want to **manually create a Signal** from any message? → Use the `•••` menu (no `/bb connect` needed)
  * Want to **submit structured feedback** (with CRM contact lookup)? → Use `/bb feedback`
  * Want to **send call summaries from a workflow**? → Use the Slack channel picker in the workflow editor
  * Want to **ask BuildBetter questions from Slack**? → Mention the bot or use Slack's AI assistant panel
</Tip>

## What It Does

BuildBetter connects to Slack in four distinct ways:

### Option 1: Channel Connection (Requires `/bb connect`)

Connect entire channels to BuildBetter for automated workflows:

**Push Summaries** - Share call summaries automatically to channels
**Import Conversations** - Automatically monitor and create Signals from channel messages (with live ingestion and backfill)
**Topics Source** - Use a channel as a source for the Topics experience (channels are gated — only channels explicitly set to track topics are processed)
**Workflows** - Make the channel available in workflow Slack actions without setting it up for imports

<Warning>
  You **must** run `/bb connect` in a channel to enable automatic Signal creation, push summaries, Topics ingestion, or workflow posting for that channel.
</Warning>

### Option 2: Manual Signal & Feedback Creation

Create Signals or submit feedback on-demand:

* Right-click any message → **Create Signal in BuildBetter** (no `/bb connect` required)
* Run **`/bb feedback`** to open a feedback modal — captures structured customer feedback with CRM contact search and your custom properties
* Works in **any channel** where BuildBetter is installed

### Option 3: Workflow Integration

Slack is a first-class destination inside BuildBetter workflows. The workflow editor includes a **Slack channel picker** for channels connected with **Workflows** or **Push Summaries** — no more manual webhook URLs. Slack actions run through the connected Slack bot with automatic token refresh.

### Option 4: Slack Agent

Use BuildBetter directly from Slack by mentioning the bot in a channel or opening Slack's AI assistant panel. The Slack Agent supports:

* Analysis workflows grounded in BuildBetter data
* Formatted answers with citations
* Charts, highlights, and task results
* Suggested prompts
* Thread-aware conversations so follow-up questions keep context

<Info>
  Slack Agent access follows your BuildBetter organization permissions and the Slack workspace connection.
</Info>

## Setup Instructions

### Prerequisites

* Active Slack workspace with admin permissions to install apps
* BuildBetter organization admin access
* The Slack channel where you want to connect BuildBetter

### Step 1: Install BuildBetter App in Slack

1. **Connect from BuildBetter**
   * Go to Settings → Integrations in BuildBetter
   * Find Slack in the Communication category
   * Click "Connect"

2. **Authorize in Slack**
   * Sign in to your Slack workspace
   * Review and approve the permissions
   * Click "Allow" to install the app

After installation, BuildBetter is available in your Slack workspace. Now you can choose how to use it:

### Step 2A: Connect a Channel (For Imports, Summaries, Topics, or Workflows)

<Note>
  **Required** if you want automatic Signal creation, automatic call summaries, Topics ingestion, or workflow Slack actions in this channel.
</Note>

1. **Go to the channel** you want to connect in Slack
2. **Invite BuildBetter** (if private channel): `/invite @BuildBetter`
3. **Run the connect command**: `/bb connect`
4. **Select your organization** from the dropdown
5. **Choose connection type:**
   * **Push Summaries** - Share call summaries to this channel
   * **Import Conversations** - Automatically scrape messages and create Signals (with live ingestion and backfill)
   * **Topics Source** - Make this channel a source for Topics ingestion
   * **Workflows** - Make this channel selectable from workflow Slack actions
6. **Click "Confirm"**

<Note>
  **Private confirmation:** The connection confirmation is now shown only to the person who ran `/bb connect`, reducing channel noise for everyone else.
</Note>

### Step 2B: Manual Signal Creation (No Connection Needed)

<Note>
  You can create Signals manually from **any** message without running `/bb connect`
</Note>

No setup needed! Once the BuildBetter app is installed, you can:

* Right-click any message
* Select "Create Signal in BuildBetter"
* Works immediately in any channel where BuildBetter is installed

## How to Use

### Using Connected Channels (Requires `/bb connect`)

These features **only work in channels where you've run `/bb connect`**:

#### Push Summaries Mode

**From BuildBetter:**

1. Open any call recording in BuildBetter
2. Click "Share" → "Share to Slack"
3. Select the connected channel
4. BuildBetter posts the summary to that channel

**Automatic Sharing (via Workflows):**

* Set up workflows in BuildBetter to automatically share summaries
* Example: Share all customer success calls to `#customer-success`

#### Workflows Mode

Use **Workflows** mode when a channel should receive workflow messages but should not be imported for Signals or Topics.

* The channel appears in the workflow editor's Slack channel picker
* The channel appears under **Available to workflows** in Slack integration settings
* Workflow posting can be configured without enabling message-history import

<Info>
  **Workflows** and **Push Summaries** remain available even when your Slack app does not have channel-history import permissions. **Import Conversations** is the mode that requires message-history access.
</Info>

#### Import Conversations Mode

**Automatic Daily Scraping:**

* BuildBetter monitors the connected channel for new messages
* Runs daily to check for customer conversations
* Automatically creates Signals from relevant threads
* No manual action needed—it just works in the background

<Warning>
  Automatic Signal creation **only happens** in channels where you ran `/bb connect` and selected "Import Conversations"
</Warning>

### Manual Signal Creation (Works Anywhere)

You can create Signals from **any** message in **any** channel—no `/bb connect` needed:

1. **Hover over the message** you want to turn into a Signal
2. **Click the `•••` menu** (or right-click the message)
3. **Select "Create Signal in BuildBetter"** from the shortcuts menu
4. **Choose the interaction type:**
   * **Internal** - For team discussions and internal feedback
   * **External** - For customer conversations and support threads
5. **Click "Create"**
6. BuildBetter adds a :memo: reaction and processes the Signal

**What Gets Analyzed:**

* Message text and entire thread
* Sender information (automatically creates people in BuildBetter)
* Timestamp and context
* Channel information

## Message Ingestion Behavior

### Live Ingestion + Backfill

Once a channel is connected with **Import Conversations** or as a **Topics Source**, BuildBetter ingests new messages in near real time and backfills historical messages so you don't lose context.

* **Backfills cover threaded, non-threaded, and single-message conversations** by default
* **Backfill grouping:** Related closed conversations are no longer split into duplicates during backfill
* **Buffered message flushing:** Buffered Slack messages are flushed reliably even if a worker restarts

### Channel Gating for Topics

Only channels explicitly configured to **track topics** are processed for Topics ingestion. This gives admins precise control over which channels contribute to topic discovery — noisy channels can stay connected for other purposes without contaminating topic signal.

### Channel-Purpose Context

When a channel's purpose/description is set in Slack, BuildBetter uses it as context for topic classification, improving naming and routing for topics derived from that channel.

### Edited Messages

When a Slack message is edited:

* The stored conversation text is refreshed so downstream content stays current
* Threaded replies that are edited reprocess correctly so classification, topics, and signal extraction stay accurate

### Multi-Org Shared Channels

For Slack workspaces connected to **multiple BuildBetter organizations** (including shared channels):

* Messages and edits are routed correctly to **every connected org**
* Duplicate creation from repeated imports, retries, or polling is prevented
* Recovery after rate limits resumes imports from the correct cursor without dropping or duplicating messages

### Source Context on Evidence

Signals and evidence from Slack now include clearer source context — the channel name, platform label, and a link back to the original message — so you can always tell where a piece of evidence came from.

## Configuration

### Connection Types

**Push Summaries:**

* Best for: Sharing insights with your team
* Use cases: Post call summaries, share highlights, notify about important conversations
* Permissions needed: Post messages, read channels

**Workflows:**

* Best for: Posting workflow-generated alerts, summaries, and routing updates
* Use cases: Send high-severity signals to a support channel, post account updates, route research findings
* Permissions needed: Post messages to the connected channel
* Settings view: Connected channels appear under **Available to workflows**

**Import Conversations:**

* Best for: Customer support, community channels, feedback channels
* Use cases: Analyze customer issues, track feature requests, monitor sentiment
* Permissions needed: Read message history, post messages, add reactions
* Schedule: Imports run daily by default (configurable)

### Message Import Options

When configuring Import Conversations mode, you have control over how messages are processed:

**Import All Messages**
By default, only threaded conversations (messages with replies) are imported. Enable "Import all messages" to also capture standalone messages without replies. This is ideal for:

* Feedback channels where each post is its own entry
* Announcement channels with individual updates
* Channels where conversations happen in single messages

**Message Grouping**
When importing standalone messages, you can choose how they're processed:

| Setting                              | Behavior                                                 | Best For                                                   |
| ------------------------------------ | -------------------------------------------------------- | ---------------------------------------------------------- |
| **Group related messages** (default) | AI groups related standalone messages into conversations | General channels with flowing discussions                  |
| **Treat as separate conversations**  | Each standalone message becomes its own conversation     | Dedicated feedback channels where each post is independent |

<Tip>
  For channels like `#customer-feedback` where each message is a distinct piece of feedback, enable both "Import all messages" and "Treat as separate" to ensure each feedback item is captured individually.
</Tip>

### Managing Connections

**View All Connections:**

* Go to Settings → Integrations → Slack in BuildBetter
* See all connected channels and their types
* Check **Available to workflows** to confirm which channels can be used by workflow Slack actions
* Edit or disconnect channels

**Connect Multiple Channels:**

* Run `/bb connect` in each channel you want to connect
* Each channel can have a different connection type
* You can connect the same workspace to multiple BuildBetter organizations

**Disconnect a Channel:**

* Go to Settings → Integrations → Slack in BuildBetter
* Click "Disconnect" next to the channel
* Or uninstall the BuildBetter app from your Slack workspace

## Slack Commands

Use these commands in any Slack channel where BuildBetter is installed:

**`/bb connect`**

* Connect the current channel to BuildBetter
* Choose Push Summaries, Import Conversations, Topics Source, or Workflows mode
* Must be run in a channel (not DMs)

**`/bb feedback`**

* Open the feedback modal to capture structured customer feedback
* After submission, you'll see a **View in BuildBetter** link to jump straight to the submitted feedback and related insights

**`/bb help`**

* Show available commands and features
* Get quick help without leaving Slack

## Slack Feedback Modal

The `/bb feedback` command opens a modal that mirrors BuildBetter's feedback intake — designed so reps can capture customer input without leaving Slack.

**What's in the modal:**

* **CRM Contact Search** — Search and select **HubSpot** or **Salesforce** contacts directly from the modal. Selecting a contact automatically deduplicates and creates or updates the person record in BuildBetter.
* **Dynamic Custom Properties** — The modal shows all custom properties configured for your organization, with the right input type for each:
  * **Text fields** — free-form input
  * **Select fields** — single-select dropdowns
  * **Hierarchy fields** — multi-select taxonomy nodes with live search and hierarchical display
  * **User fields** — pick a teammate
* **Signal Type & Speaker** — set the signal type, attach a speaker (search existing or create new), and add taxonomy tags inline
* **Title & Context** — capture a title and supporting context alongside the message
* **View in BuildBetter** — after submission, jump directly to the feedback record

## Two Ways to Create Signals from Slack

### Automatic (Requires `/bb connect`)

**Setup Required:**

1. Run `/bb connect` in the channel
2. Select "Import Conversations" mode
3. BuildBetter will automatically check for new messages daily

**What Happens:**

* Monitors channel continuously
* Creates Signals from customer conversations automatically
* No manual action needed after setup

<Warning>
  Automatic scraping **only works** in channels where you ran `/bb connect` and selected "Import Conversations"
</Warning>

### Manual (Works in Any Channel)

**No Setup Required:**
Use the message `•••` menu to create Signals on-demand

**How to Use:**

1. Hover over **any** Slack message
2. Click the `•••` menu (message actions)
3. Select "Create Signal in BuildBetter"
4. Choose Internal or External interaction type
5. Click "Create"

**What Happens:**

* BuildBetter processes the message and thread immediately
* Creates a new Signal with extracted topics, impacts, and emotions
* Adds a :memo: reaction to the original message
* Posts a confirmation in the thread
* Signal appears in your BuildBetter dashboard with link to original Slack message

<Tip>
  Manual Signal creation works in **any** channel where BuildBetter is installed—even if you haven't run `/bb connect`
</Tip>

## Troubleshooting

### Installation Issues

**"BuildBetter is not authorized"**

* Go to Settings → Integrations in BuildBetter and reconnect
* Make sure you have permission to install apps in your Slack workspace
* Check with your Slack admin if app installations are restricted

**"/bb connect doesn't work"**

* Make sure you're in a channel (not a DM)
* Verify BuildBetter is installed in your workspace
* Try `/invite @BuildBetter` first, then `/bb connect`

**"You need to update your app connection"**

* BuildBetter added new features that require additional permissions
* Go to Settings → Integrations → Slack in BuildBetter
* Click "Reconnect" to reauthorize with updated permissions

### Connection Issues

**"You are not connected to any organization"**

* First connect Slack in BuildBetter: Settings → Integrations → Slack
* Make sure you authorized the app
* Then run `/bb connect` in your Slack channel

**"You are already connected this channel"**

* The channel is already connected to a BuildBetter organization
* Go to Settings → Integrations → Slack to manage existing connections
* Disconnect first if you want to change the connection type

### Message Import Issues

**"Signals not being created automatically"**

* Verify the channel is connected with "Import Conversations" mode
* Check that the import schedule is active (daily by default)
* Ensure BuildBetter has "channels:history" or "groups:history" permission
* Messages must have text content (attachments-only messages aren't supported)

**"Can't create Signal from message"**

* Message must contain text (not just images or attachments)
* BuildBetter must be invited to the channel
* You must be connected to a BuildBetter organization
* Check billing credits haven't been exceeded

**"Signal creation says not enough credits"**

* Your BuildBetter plan has run out of conversation import credits
* Check your billing status in BuildBetter
* Contact BuildBetter support to upgrade your plan

### Push Summary Issues

**"Can't share to Slack channel"**

* Verify the channel is connected with "Push Summaries" mode
* Check that BuildBetter is still invited to the channel
* Ensure the Slack app hasn't been uninstalled
* Try reconnecting in Settings → Integrations

**"Private channel won't receive summaries"**

* BuildBetter must be explicitly invited to private channels
* Type `/invite @BuildBetter` in the private channel
* Then run `/bb connect` to set up the connection

## Privacy & Security

**Channel Access:**

* BuildBetter only reads channels where it's explicitly invited
* Private channel messages are only accessible if BuildBetter is a member
* You control which channels are connected

**Data Handling:**

* All data is encrypted in transit and at rest
* OAuth tokens are securely stored
* BuildBetter only accesses the channels you configure
* You can disconnect at any time

**Message Visibility:**

* Imported messages respect Slack's privacy settings
* Signals created from Slack are visible to your BuildBetter organization
* You control who in BuildBetter can see imported conversations

## Best Practices

**Start with Customer-Facing Channels**
Connect channels like `#customer-support` or `#feedback` first to maximize Signal value.

**Choose the Right Mode**

* Use "Push Summaries" for internal team channels where you want to share insights
* Use "Import Conversations" for channels with customer feedback and support requests

**Use Message Shortcuts for Quick Signals**
Right-click any important message and create a Signal immediately—don't wait for automatic import.

**Set Up Multiple Channels**
Connect different channels with different modes based on how your team uses Slack.

**Review Signals Regularly**
Check your BuildBetter Signals dashboard to see what's being extracted from Slack.

**Notify Channel Members**
Let your team know BuildBetter is monitoring the channel and creating Signals from conversations.

## Slack in Workflows

Slack steps inside BuildBetter workflows use the connected Slack bot — no webhook URLs to copy around:

* **Channel Picker:** Choose a channel connected with **Workflows** or **Push Summaries** directly from a dropdown in the workflow editor
* **Available to Workflows:** Slack settings list the channels that workflow actions can use
* **Automatic Token Refresh:** Slack actions keep working even after tokens rotate
* **Better Setup Guidance:** Errors and missing-channel states are surfaced clearly inside the editor
* **Real Error Messages:** When a Slack step fails, you see the actual channel error rather than a generic failure

You can also send **Slack thread updates** from custom object pages so the channel stays in the loop on status changes.

## Workspace-Level Integration

* One Slack workspace can connect to multiple BuildBetter organizations
* Each channel can only be connected to one BuildBetter organization at a time
* Shared channels across multiple connected orgs are handled correctly — messages and edits route to every connected org
* If multiple team members connect Slack, they share the same workspace integration
* Uninstalling the BuildBetter app removes all channel connections

## Support

Need help with Slack integration?

* Type `/bb help` in any Slack channel where BuildBetter is installed
* Check connection status in Settings → Integrations → Slack
* Verify BuildBetter is invited to the channel
* Contact BuildBetter support with your workspace name and channel details