Skip to main content
Connect your own Slack app to a Gummie agent for custom branding, dedicated bot identity, and advanced enterprise deployments.
This is an advanced feature. For most users, we recommend using the standard Gumloop Slack integration, which is simpler to set up and works great for the majority of use cases. Only use a custom Slack app if you have specific requirements for branding, multiple agents, or enterprise compliance.

​
When to Use a Custom Slack App

The standard Gumloop integration (@Gumloop) is the fastest way to get agents into Slack—it works out of the box with minimal setup. However, there are scenarios where connecting your own custom Slack app makes sense:

Custom Branding

Give your agent a unique name and avatar that reflects its purpose—like “Sales Assistant” or “Support Bot” instead of “@Gumloop”

Multiple Agents, Same Workspace

Run multiple agents with distinct identities in the same Slack workspace without confusion

Enterprise Compliance

Meet IT security policies that require all Slack integrations to be owned and managed internally

White-Label Solutions

Build products or services with AI agents that appear under your brand, not Gumloop’s

​
Standard Integration vs Custom Slack App

Start with the standard integration first. If you find you need custom branding or multiple agents later, you can always add a custom Slack app.

​
Prerequisites

Before setting up a custom Slack app, ensure you have:
  • Admin access to your Slack workspace (to create and install apps)
  • Permission to create Slack apps at api.slack.com

​
Setup Options

Gumloop offers two ways to connect a custom Slack app to your agent:
Best for: Users who don’t have an existing Slack app and want the fastest setup experience.Gumloop provides a pre-configured manifest that automatically sets up all the required permissions and event subscriptions for you. This is the easiest path.
This guided workflow walks you through creating a new Slack app with all the correct settings pre-configured.
1

Open the Slack Connection Dialog

In your agent, click the “Add to Slack” button in the top bar.
Add to Slack button in the agent top bar
In the connection dialog, select the “Custom App” tab.
Custom App tab in the Add to Slack dialog showing New App and Existing App options
2

Choose New App

A modal will appear asking how you’d like to connect your Slack app. Select “New App” to create a fresh Slack app with Gumloop’s pre-configured settings.
Modal showing New App and Existing App options
3

Customize Your App

Enter the details for your custom Slack app:
  • App Name: The display name your bot will have in Slack (e.g., “Sales Assistant”, “Support Bot”)
  • App Tag: The @mention handle for your bot (e.g., @salesassistant)
  • App Description (optional): A description others will see when viewing your app in Slack
Customization modal with App Name, App Tag, and App Description fields
Choose a descriptive name that reflects what your agent does. This is what your team will see when the bot responds in Slack.
Click “Next” when you’re done.
4

Follow the Setup Guide

Gumloop provides a step-by-step setup guide with everything you need:
Setup Guide showing 5 steps to create and configure the Slack app
Here’s what to do:
  1. Copy the Slack manifest JSON — Click the “Copy” button. This manifest contains all the pre-configured permissions, scopes, and event subscriptions your app needs.
  2. Create a new Slack app — Click “Open” to go to api.slack.com/apps, then:
    • Click “Create New App”
    • Choose “From an app manifest”
    Slack App from Manifest Option
    • Select your Slack workspace
  3. Paste the manifest JSON — In the manifest editor, paste the JSON you copied from Gumloop. This automatically configures:
    Paste Gumloop's Slack Manifest Code here
    • All required bot token scopes (including the im:* scopes needed for direct messages)
    • Event subscriptions with the correct webhook URL (including message.im for DMs)
    • Interactivity with the correct request URL
    • The App Home Messages tab, so users can DM your bot
    • Bot user settings
  4. Complete installation in Slack — Review the app settings and click “Create”, then “Install to Workspace” and authorize the app.
  5. Return to Gumloop — Come back to this page and click “Next” to continue.
5

Enter Your App Credentials

After creating your Slack app, you’ll need to provide credentials from Slack’s Basic Information page.
Credential entry form requesting Client ID, Client Secret, and Signing Secret
In your Slack app settings, go to “Basic Information” and copy:
  • Client ID — Found under “App Credentials”
  • Client Secret — Click “Show” to reveal, then copy
  • Signing Secret — Click “Show” to reveal, then copy
Credential entry form requesting Client ID, Client Secret, and Signing Secret
Never share your Client Secret or Signing Secret publicly. Treat them like passwords.
Click “Connect to Slack” to complete the OAuth flow and authorize the connection.
6

Ensure Slack App is Installed to the Workspace

Make sure your Slack app is installed to your workspace. If you skipped this step earlier, go to your Slack app settings → OAuth & Permissions → Install to Workspace.
Install Custom Slack App
7

Invite Your Bot to Channels

Your custom bot needs to be invited to channels where you want it to work.In Slack, go to each channel and type:
Replace @YourBotName with the App Tag you configured (e.g., @salesassistant).
Slack channel showing bot being invited with /invite command
Your custom Slack app agent is now ready! @mention your bot in a channel, or send it a direct message, to start a conversation.
Already connected a custom Slack app before direct messages were supported? Existing apps won’t receive DMs until you update them. See Enabling DMs on an already-connected app.

​
Option 2: Connect an Existing App

If you already have a Slack app or need custom configurations, you can connect it directly to Gumloop.
1

Open the Slack Connection Dialog

In your agent, click the “Add to Slack” button in the top bar, then select the “Custom App” tab in the connection dialog.
Add to Slack button in the agent top bar
2

Choose Existing App

Select “Existing App” to connect a Slack app you’ve already created.
Modal showing New App and Existing App options
3

Configure Your Slack App (If Not Already Done)

Before connecting, ensure your existing Slack app has the required configuration:
In your Slack app settings, go to OAuth & Permissions and add these scopes:
The im:history, im:read, and im:write scopes are what allow users to direct message your bot. If you leave them out, DMs won’t reach your agent.
Optionally, add assistant:write to have your bot appear in Slack’s agents & assistants dropdown (top right of the Slack client). It isn’t required for DMs or mentions to work—see Enabling DMs on an already-connected app.
In your Slack app settings, go to Event Subscriptions:
  1. Toggle “Enable Events” to ON
  2. Set the Request URL to:
  3. Wait for verification (green checkmark)
  4. Under “Subscribe to bot events”, add:
    • app_mention
    • message.channels
    • message.groups (for private channels)
    • message.im (for direct messages)
  5. Save changes
To let users direct message your bot, you must expose the writable Messages tab. In your Slack app settings, go to Features → App Home:
  1. Under Show Tabs, enable the Messages Tab.
  2. Check “Allow users to send Slash commands and messages from the messages tab”.
Slack App Home settings with the Messages Tab enabled and the 'Allow users to send Slash commands and messages from the messages tab' checkbox selected
Without this, Slack hides the message box in your bot’s DM view and users can’t message it directly.
In your Slack app settings, go to Interactivity & Shortcuts:
  1. Toggle “Interactivity” to ON
  2. Set the Request URL to:
  3. Save changes
This enables your custom Slack app to handle interactive components like button clicks, modal submissions, and form responses from your agent.
Go to OAuth & Permissions and click “Install to Workspace” if you haven’t already. Authorize the app when prompted.
4

Enter Your App Credentials

Provide the credentials from your Slack app’s Basic Information page:
Credential entry form requesting Client ID, Client Secret, and Signing Secret
  • Client ID — Found under “App Credentials”
  • Client Secret — Click “Show” to reveal, then copy
  • Signing Secret — Click “Show” to reveal, then copy
Click “Connect to Slack” to complete the OAuth flow.
5

Assign to Your Agent and Invite to Channels

Select your custom Slack app credential from the dropdown and click “Add”.Then invite your bot to channels in Slack:

​
Enabling DMs on an Already-Connected App

Direct message support was added after custom Slack apps first launched. If you connected your custom app before DMs were available, the missing piece is the App Home Messages tab—without it, Slack hides the message box so users can’t DM your bot. The message.im event subscription and the im:* scopes were already part of Gumloop’s manifest, so apps created with the New App flow already have them and there’s nothing new to add. Enable DMs with the one-time steps below.
1

Enable the App Home Messages tab

In your Slack app settings at api.slack.com/apps, go to Features → App Home and, under Show Tabs:
  1. Enable the Messages Tab.
  2. Check “Allow users to send Slash commands and messages from the messages tab”.
Slack App Home settings with the Messages Tab enabled and the 'Allow users to send Slash commands and messages from the messages tab' checkbox selected
2

Reinstall the app to your workspace

Go to Settings → Install App (or OAuth & Permissions) and click “Reinstall to Workspace”, then authorize when prompted. This applies the App Home change so DMs start reaching your agent.
Slack Install App settings showing the Bot User OAuth Token and the Reinstall to Workspace button
You don’t need to reconnect the credential in Gumloop. Your existing credential already has the scopes required to send DMs (chat:write and im:write), so once the Messages tab is enabled and the app is reinstalled, DMs work without re-authorizing.
3

(Existing apps only) Verify the DM event and scopes

If you connected an existing app you built yourself—rather than using Gumloop’s New App manifest—confirm it’s configured for DMs:
  • Event Subscriptions → Subscribe to bot events includes message.im.
  • OAuth & Permissions → Bot Token Scopes includes im:history, im:read, and im:write.
If you add any of these, reinstall the app again so the changes take effect. Apps created with Gumloop’s New App manifest already have all of this.
4

(Optional) Add the assistant:write scope to show your bot in Slack's agents list

Slack only lists an app in the agents & assistants dropdown (the icon in the top right of the Slack client) if the app has the assistant:write bot scope. This scope is not part of Gumloop’s New App manifest, so apps created or re-created from the manifest lose their spot in that list until you add it back.To add it, go to OAuth & Permissions → Bot Token Scopes, add assistant:write, then reinstall the app to your workspace.
Slack Agents dropdown listing custom Slack app bots
assistant:write is optional—DMs work without it. It only controls whether your bot appears in Slack’s agents & assistants dropdown as a shortcut for starting a DM.

​
Using Your Custom Slack App Agent

Once set up, interacting with your custom Slack app agent works similarly to the standard Gumloop integration, with a few key differences.

​
Starting a Conversation

@mention your custom bot in any channel where it’s been invited:
Interaction with Custom Slack App
The agent will:
  1. Process your request using its configured tools and workflows
  2. Respond in a thread to keep conversations organized
  3. Continue the conversation within the thread based on your agent’s settings
Thread commands work here too! Type !stop to stop the agent’s response, or !link to get a link to view the conversation in Gumloop.

​
Direct Messages (DMs)

Your custom bot can also be messaged directly—no channel or @mention required. Open a DM with your bot from the Slack sidebar (or the Messages tab on the app’s profile) and just start typing:
Each top-level message you send starts a new conversation; reply within that message’s thread to continue the same conversation.
DMs are unique to custom Slack apps. The standard Gumloop integration works in public and private channels only.
DMs require the App Home Messages tab to be enabled and the im:history, im:read, and im:write scopes to be granted. Apps created with Gumloop’s New App manifest have this configured automatically. If you connected an existing app—or linked a custom app before DM support shipped—follow Enabling DMs on an already-connected app.

​
Interactive Features

Custom Slack apps fully support Slack interactive components. Your agent can send messages with buttons, open modals, and collect form responses, just like the standard Gumloop integration. Supported interactive components include:
  • Button clicks — Respond to action buttons in agent messages
  • Modal submissions — Collect structured input through Slack modals
  • Form responses — Process multi-field form submissions from users
Interactive features require the Interactivity Request URL to be configured. If you used Gumloop’s manifest to create your app, this is already set up. For existing apps, see the Interactivity configuration step above.

​
Key Differences from Standard Integration

Custom Slack apps don’t support /gummie slash commands. You cannot use:
  • /gummie add — Bot is added by inviting to channels instead
  • /gummie remove — Remove bot by kicking from channels
  • /gummie active — You know which bot is in a channel by its name
  • /gummie help — Not available
To manage your custom app agent:
  • Add to channels: /invite @YourBotName
  • Remove from channels: /kick @YourBotName or remove via channel settings
Unlike the standard integration which is channel-specific, your custom Slack app works in any channel where it’s invited. You don’t need to “add” the agent to each channel—just invite the bot.
Your agent appears with whatever name and avatar you configured in Slack’s app settings. Team members interact with @YourBotName instead of @Gumloop.

​
Slack Preferences

All the same Slack preferences available for standard agents apply to custom Slack apps:
  • Thread Response Trigger: Control whether the agent responds to all messages in a thread or only when @mentioned
  • Stream Reasoning: Show or hide the agent’s thought process
  • Hide Workflow Run Results: Show or hide workflow execution details
Configure these in your agent’s settings under Slack Preferences.
Slack preferences settings panel

​
Credential Ownership Options

When creating your custom Slack app credential, you can choose who has access:

​
Troubleshooting

Check these items:
  • Is the Slack app installed to your workspace? This is the most common issue. Go to your Slack app settings → OAuth & Permissions → Install to Workspace.
    Install Custom Slack App to Workspace
  • Is the bot invited to the channel? (/invite @YourBotName)
  • Did you @mention the bot in your message?
  • Are the event subscriptions configured correctly in Slack?
  • Is the webhook URL verified? (https://api.gumloop.com/api/v1/external/slack/events)
  • Is the credential properly assigned to your agent in Gumloop?
  • Does the user have a Gumloop account with matching email?
Check these items:
  • Is the App Home Messages tab enabled? Go to your Slack app settings → Features → App Home → enable the Messages Tab and check “Allow users to send Slash commands and messages from the messages tab”.
  • Is message.im subscribed under Event Subscriptions → Subscribe to bot events?
  • Are the im:history, im:read, and im:write scopes granted under OAuth & Permissions?
  • Did you connect this app before DM support shipped? The App Home Messages tab was added to the manifest later, so older apps have it disabled. Enable the Messages tab and reinstall the app—no need to reconnect the credential in Gumloop. See Enabling DMs on an already-connected app.
Check:
  • Is the bot invited to the non-working channels?
  • For private channels, do you have groups:history and groups:read scopes configured?
  • Is there a different agent assigned via the standard integration in that channel?
The URL https://api.gumloop.com/api/v1/external/slack/events should verify automatically.If it fails:
  • Check for typos in the URL
  • Ensure you’re using HTTPS (not HTTP)
  • Try again after a few minutes (temporary network issues)
  • Contact Gumloop support if the issue persists
If interactive components (buttons, modals, form submissions) are not working:
  • Is Interactivity enabled? Go to your Slack app settings → Interactivity & Shortcuts → ensure the toggle is ON
  • Is the Request URL correct? It should be set to https://api.gumloop.com/api/v1/external/slack/interactive
  • Is the Signing Secret correct? Gumloop uses your app’s Signing Secret to verify interactive payloads. Re-check the value in Basic Information → App Credentials
  • Did you use the manifest? If you created your app using Gumloop’s manifest, interactivity is pre-configured. If you connected an existing app, you may need to add this manually.
In your Slack app at api.slack.com/apps:
  • Client ID, Client Secret, Signing Secret: Found in Basic Information → App Credentials
  • Click “Show” next to each secret to reveal it, then copy

​
Important Limitations

One Agent Per Custom App

Each custom Slack app credential can only be assigned to one Gummie agent. Create separate Slack apps for each agent you need.

No Slash Commands

Custom Slack apps don’t support /gummie commands. Manage your bot by inviting/removing it from channels directly.

Credential Exclusivity

A custom Slack app credential cannot be shared between multiple agents. Assigning it to a second agent removes it from the first.

Manual Channel Management

Unlike the standard integration, you must manually invite your custom bot to each channel where you want it to work.

​
Security Considerations

Your Slack app’s Client Secret and Signing Secret are stored securely in Gumloop and used to verify that incoming webhooks and interactive payloads are actually from Slack. Both event callbacks and interactive component actions (button clicks, modal submissions) are verified using your app’s Signing Secret before processing. Never share these secrets or expose them in logs.
Users must have matching email addresses in Slack and Gumloop for the integration to work. This ensures proper authentication and prevents unauthorized access.
Before processing messages, Gumloop verifies:
  • The user has a valid Gumloop account
  • The user has permission to access the agent
  • For team agents, team membership is verified

​
FAQ

Yes! They operate independently. The standard bot uses channel-based mapping with /gummie commands, while custom apps use bot-based mapping with direct invites. You can have both active in different channels.
New App uses a pre-configured manifest that automatically sets up all required permissions and events—it’s faster and less error-prone. Existing App lets you connect a Slack app you’ve already created, but you’re responsible for ensuring all scopes and events are configured correctly.
The credential in Gumloop will stop working immediately. You’ll need to create a new app and set it up again.
Update these in your Slack app settings at api.slack.com/apps. Changes will reflect in Slack automatically—no changes needed in Gumloop.
Yes! This is useful when you want the same agent available in multiple Slack workspaces. Each workspace installation creates a separate credential, and you can assign all of them to a single agent.

​
Next Steps

Build Your First Agent

Learn how to create and configure agents in Gumloop

Standard Slack Integration

Review the standard Slack setup if you haven’t used it yet

Managing Credentials

Learn more about credential types and management