# Slack (NEW) {% embed url="" %} To integrate Slack with your Voiceflow project, you will need to follow the same steps as shown in the [quick start](https://docs.flowbridge.app/documentation/getting-started/quickstart) section. In short, in the admin panel, you will need to: 1. Create a Client Company 2. Create a Voiceflow Project and associate the Voiceflow project to the Client Company 3. 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 {% stepper %} {% step %} ### Create a Slack App * Go to * 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" {% endstep %} {% step %} ### Configure Bot Permissions 1. In your app settings, go to "OAuth & Permissions" 2. Scroll down to the "Scopes" section 3. 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 {% endstep %} {% step %} ### Set Up Event Subscriptions 1. Go to "Event Subscriptions" in your app settings 2. Toggle "Enable Events" to On 3. 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 4. Under "Subscribe to bot events", add these events: * `app_mention` - When your bot is mentioned with @ * `message.im` - Direct messages to your bot 5. Click "Save Changes"
{% endstep %} {% step %} ### Configure Interactive Components (Required for Buttons) 1. Go to "Interactivity & Shortcuts" in your app settings 2. Toggle "Interactivity" to On 3. In the "Request URL" field, enter your interactive 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 4. 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. {% endstep %} {% step %} ### Install the App to Your Workspace 1. Go to "Install App" in your app settings 2. Click "Install to Workspace" 3. Review the permissions and click "Allow" 4. Copy the "Bot User OAuth Token" (starts with `xoxb-`) {% endstep %} {% step %} ### Configure Your Application 1. In your environment's admin panel, create or edit a client integration 2. Set the integration type to "Slack" 3. Configure the following fields: * Slack Access Token: Paste the Bot User OAuth Token from the previous step {% endstep %} {% step %} ### (Again) Configure Interactive Components (Required for Buttons) Important: This step is required for Voiceflow choice responses to display as interactive buttons. 1. Go back to your Slack app's "Interactivity & Shortcuts" settings 2. Toggle "Interactivity" to On 3. 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 4. 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. {% endstep %} {% step %} ### 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 {% endstep %} {% endstepper %} ## 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 1. Check that the webhook URL is correctly configured in Slack 2. Verify the Bot User OAuth Token is correct 3. Ensure the bot has the required permissions 4. Check application logs for errors
URL Verification Failed 1. Make sure your webhook URL is publicly accessible 2. Verify the URL format matches the expected pattern
Permission Errors 1. Verify all required bot scopes are added (see Step 2 for complete list) 2. Important: After adding new scopes, you MUST reinstall the app to your workspace 3. 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: 1. 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 2. Reinstall the app after adding scopes 3. New conversations will automatically show real names 4. Existing conversations will update when the next message is sent
Media/File Issues Problem: Voice notes or media files not working Solution: 1. Verify `files:read` scope is added 2. Verify `files:write` scope is added (for sending media) 3. Reinstall the app after adding scopes 4. Check application logs for specific file download errors
Message Not Processed 1. Ensure your tenant has sufficient credits 2. Check that the Voiceflow project is properly configured 3. Verify the integration is active and properly set up
Interactive Buttons Not Working 1. Verify the `commands` scope is added to your bot permissions 2. Check that Interactive Components are enabled in your Slack app 3. Ensure the Interactive Components Request URL is correctly configured 4. Verify the URL includes the correct client integration ID 5. Test that the interactive endpoint is accessible from Slack's servers
## Security Considerations * The Bot User OAuth Token should be kept secure * Regularly rotate access tokens ## Rate Limits Slack has rate limits for API calls: * Tier 1: 1+ requests per minute * Tier 2: 20+ requests per minute * Tier 3: 50+ requests per minute * Tier 4: 100+ requests per minute