Slack (NEW)

To integrate Slack with your Voiceflow project, you will need to follow the same steps as shown in the quick start section. In short, in the admin panel, you will need to:

Create a Client Company
Create a Voiceflow Project and associate the Voiceflow project to the Client Company
Create a Client Integration and associate the Client Company & Voiceflow Project to the integration

Prerequisites

Access to a Slack workspace where you can create apps
Admin access to your application
A configured Voiceflow project
An active client integration in your system

Create a Slack App

Go to https://api.slack.com/apps
Click "Create New App"
Choose "From scratch"
Enter your app name (e.g., "Your Bot Name")
Select the workspace where you want to install the app
Click "Create App"

Configure Bot Permissions

In your app settings, go to "OAuth & Permissions"
Scroll down to the "Scopes" section
Under "Bot Token Scopes", add the following permissions:

Required Scopes

Scope

Purpose

Required For

app_mentions:read

Receive @mentions in channels

Channel interactions

channels:history

Read channel message history

Channel context

channels:read

View channel information

Display channel names in chat UI

chat:write

Send messages to users and channels

All messaging

commands

Handle interactive components

Interactive buttons and components

files:read

Download files, voice notes, and media

Media handling & voice transcription

files:write

Upload files to Slack

Sending media to users

groups:read

View private channel information

Display private channel names

im:history

Read direct message history

Direct message context

im:read

View direct message channels

Direct messaging

users:read

Get user information

Display real user names in chat UI

Critical Scopes for Full Functionality

⚠️ Important: The following scopes are essential for the best user experience:

users:read - Without this, user names will show as User_U123456 instead of real names like "John Smith"
channels:read - Without this, channel names will show as Channel_C123456 instead of "#general"
groups:read - Without this, private channel names will show as Channel_G123456 instead of "private-team"
files:read - Without this, voice notes and media files cannot be downloaded or processed
commands - Without this, interactive buttons from Voiceflow will not work

Set Up Event Subscriptions

Go to "Event Subscriptions" in your app settings
Toggle "Enable Events" to On
In the "Request URL" field, enter your webhook URL:

https://your-environment-url.flowbridge.app/v2/webhooks/slack/{your_client_integration_id}

Replace {your_client_integration_id} with your actual integration ID OR copy and paste the full URL by going to the view integration page on the integration you created, clicking the integration info button on the top right of the page

Under "Subscribe to bot events", add these events:

app_mention - When your bot is mentioned with @
message.im - Direct messages to your bot

Click "Save Changes"

Configure Interactive Components (Required for Buttons)

Go to "Interactivity & Shortcuts" in your app settings
Toggle "Interactivity" to On
In the "Request URL" field, enter your interactive webhook URL:

https://your-environment-url.flowbridge.app/v2/webhooks/slack/{your_client_integration_id}

Click "Save Changes"

Note: This endpoint will handle button clicks and other interactive components. The system will automatically process button selections and continue the Voiceflow conversation.

Install the App to Your Workspace

Go to "Install App" in your app settings
Click "Install to Workspace"
Review the permissions and click "Allow"
Copy the "Bot User OAuth Token" (starts with xoxb-)

Configure Your Application

In your environment's admin panel, create or edit a client integration
Set the integration type to "Slack"
Configure the following fields:
- Slack Access Token: Paste the Bot User OAuth Token from the previous step

(Again) Configure Interactive Components (Required for Buttons)

Important: This step is required for Voiceflow choice responses to display as interactive buttons.

Go back to your Slack app's "Interactivity & Shortcuts" settings
Toggle "Interactivity" to On
In the "Request URL" field, enter the same webhook URL as your Event Subscriptions:

https://your-environment-url.flowbridge.app/v2/webhooks/slack/{your_client_integration_id}

Replace {your_client_integration_id} with your actual integration ID from the previous steps

Click "Save Changes"

Note: The same endpoint handles both regular events and interactive components (button clicks). When users click buttons from Voiceflow choice responses, the system automatically processes the selection and continues the conversation.

Test the Integration

Test Direct Messages:

In Slack, find your bot in the "Apps" section
Send a direct message to your bot
You should receive a response from Voiceflow

Test Channel Mentions:

Invite your bot to a channel: /invite @YourBotName
Mention your bot in the channel: @YourBotName Hello!
Your bot should respond in the same channel

Webhook URL Format

The webhook endpoint follows this pattern:

POST /v2/webhooks/slack/{client_integration_id}

Where {client_integration_id} is the ID of your configured Slack integration.

Supported Features

✅ Direct Messages

Users can send direct messages to your bot
Bot responds with Voiceflow-generated content
Maintains conversation context per user

✅ Channel Mentions

Bot responds when mentioned with @ in channels
Responses are posted in the same channel
Thread support for organized conversations

✅ Message Types

Text messages (fully supported)
Interactive buttons
Image messages
Rich content from Voiceflow

Troubleshooting (FAQ)

Bot Not Responding

Check that the webhook URL is correctly configured in Slack
Verify the Bot User OAuth Token is correct
Ensure the bot has the required permissions
Check application logs for errors

URL Verification Failed

Make sure your webhook URL is publicly accessible
Verify the URL format matches the expected pattern

Permission Errors

Verify all required bot scopes are added (see Step 2 for complete list)
Important: After adding new scopes, you MUST reinstall the app to your workspace
Check that the bot is invited to channels where you're testing

Display Name Issues

Problem: Seeing User_U123456 instead of real names, or Channel_C123456 instead of channel names

Solution:

Verify these scopes are added to your bot:
- users:read - For user real names
- channels:read - For public channel names
- groups:read - For private channel names
Reinstall the app after adding scopes
New conversations will automatically show real names
Existing conversations will update when the next message is sent

Media/File Issues

Problem: Voice notes or media files not working