Skip to main content
Deploy your Airia agents as Slack bots to bring AI-powered assistance directly into your team’s Slack workspace. Users can interact with your agents through direct messages or channel conversations, creating seamless workflows within their existing communication tools.

​
Overview

The Slack Bot interface allows you to deploy agents that users can interact with directly in Slack. Once configured, your agent appears as a bot user in your workspace, ready to respond to messages, participate in channels, and assist with tasks without leaving the Slack environment.
Slack Bot deployment requires administrator access to both your Airia account and your Slack workspace.

​
Prerequisites

Before deploying an agent to Slack, you’ll need:
  • Administrator or Platform Admin access in Airia
  • Slack workspace administrator privileges
  • A deployed agent ready to connect to Slack

​
Creating a Slack App

The first step is to create a Slack app and obtain its OAuth bot token, which you’ll use to connect Airia to your Slack workspace.

​
Step 1: Create a New Slack App

  1. Navigate to https://api.slack.com/apps
  2. Click Create New App
  3. Select From scratch
  4. Enter an App Name (this will be the name of your bot in Slack)
  5. Select your Workspace from the dropdown
  6. Click Create App

​
Step 2: Enable Agents & AI Apps

  1. In the left sidebar, navigate to Features > Agents & AI Apps
  2. Toggle the Enable switch to activate this feature
  3. This enables your bot to use Slack’s AI and agent capabilities
Enabling Agents & AI Apps is required for your bot to properly function within Slack’s modern messaging infrastructure.

​
Step 3: Enable Chat Tab

  1. In the left sidebar, navigate to Features > App Home
  2. Scroll down to the Show Tabs section
  3. Make sure the Messages Tab (Chat Tab) is enabled
  4. Check the box for “Allow users to send Slash commands and messages from the messages tab”
  5. This allows users to send direct messages to your bot
The Chat Tab must be enabled and the checkbox must be checked for users to interact with your bot through direct messages. Without these settings, users won’t be able to start conversations with the bot.

​
Step 4: Configure OAuth Scopes

Your Slack bot needs specific permissions to interact with users and channels:
  1. In the left sidebar, navigate to Features > OAuth & Permissions
  2. Scroll down to the Scopes section
  3. Under Bot Token Scopes, click Add an OAuth Scope
  4. Add each of the following scopes:
Scope Descriptions:
  • assistant:write - Allows the bot to act as an AI assistant
  • chat:write - Enables the bot to send messages
  • channels:read - Lets the bot view basic public channel information
  • channels:history - Allows the bot to read message history in public channels
  • groups:read - Lets the bot view private channels it has been invited to
  • groups:write - Enables the bot to send messages to private channels it has been invited to
  • groups:history - Allows the bot to read message history in private channels and group DMs
  • mpim:history - Allows the bot to read message history in multi-person direct messages
  • im:history - Allows the bot to read direct message history
  • users:read - Enables the bot to view basic user information
  • users:read.email - Allows the bot to read user email addresses
  • files:read - Enables the bot to access shared files
In Slack’s API, public channels and private channels are distinct resource types. The channels:* scopes only grant access to public channels — private channels require the groups:* scopes. Without groups:read and groups:write, a bot that has been invited to a private channel will not be able to resolve that channel when an agent tries to send a message to it, and the agent will report that the channel cannot be found.

​
Step 5: Install the App to Your Workspace

  1. In the left sidebar, navigate to Settings > Install App
  2. Click Install to Workspace
  3. Review the permissions and click Allow
  4. You’ll be redirected back to the app settings page

​
Step 6: Copy the Bot OAuth Token

  1. After installation, you’ll see the Bot User OAuth Token on the OAuth & Permissions page
  2. The token starts with xoxb-
  3. Click Copy to copy the token to your clipboard
  4. Keep this token secure - you’ll need it in the next step
Never share your Bot OAuth Token publicly or commit it to version control. Treat it like a password. If compromised, regenerate it immediately from the Slack app settings.

​
Configuring Your Slack Bot Deployment in Airia

Now you’ll create the Slack Bot deployment and connect it to your agent:

​
Step 1: Create a Slack Bot Interface

  1. Navigate to your agent in the Airia platform
  2. Click on the Interfaces section in Agent Settings
  3. Click Add Interface or New Deployment
  4. Select Slack Bot as the interface type

​
Step 2: Add Your Slack Credential

  1. In the credential dropdown, select an existing Slack credential or click to add a new one
  2. If adding a new credential, paste your Bot OAuth Token (the xoxb- token from Step 6 above)
  3. This connects your deployment to your Slack workspace using the OAuth token
Slack credentials can be reused across multiple Slack bot deployments in your organization.

​
Step 3: Configure Execution Settings

Choose how the agent should execute when triggered from Slack: Anonymous
  • Execute without user context
  • No user mapping required
  • All messages are processed with the same permissions
  • Best for: Public bots where user identity isn’t important
Agent Creator
  • Execute as the user who created this agent
  • Uses agent creator’s permissions for all executions
  • No additional configuration needed
  • Best for: Bots with consistent permission requirements
Existing Airia User (Recommended)
  • Map Slack users to existing Airia users
  • Each user’s execution uses their own Airia permissions
  • Requires user mapping to be configured
  • Best for: Enterprise deployments with role-based access control
Select “Existing Airia User” for enterprise deployments where you need to maintain user-level permissions and audit trails.

​
Step 4: Copy the Webhook URL

After configuring the execution settings:
  1. Airia generates a Webhook Events API URL
  2. Click the Copy button to copy this URL
  3. Keep this URL handy - you’ll need it to configure Event Subscriptions in Slack
  4. Click Done to save the deployment
The webhook URL is unique to this deployment and allows Slack to send events to your Airia agent.

​
Configuring Event Subscriptions in Slack

Return to your Slack app configuration to enable event subscriptions using the webhook URL from Airia:

​
Step 1: Enable Event Subscriptions

  1. Go back to https://api.slack.com/apps and select your app
  2. In the left sidebar, navigate to Features > Event Subscriptions
  3. Toggle Enable Events to On
  4. In the Request URL field, paste the webhook URL you copied from Airia
  5. Slack will verify the URL (you should see a green checkmark if successful)
Make sure your Airia deployment is saved before Slack tries to verify the webhook URL, otherwise verification will fail.

​
Step 2: Subscribe to Bot Events

  1. Scroll down to Subscribe to bot events
  2. Click Add Bot User Event and add each of the following events:
    • message.im - Messages sent to your bot via direct message
    • message.channels - Messages posted in public channels the bot is a member of
    • message.groups - Messages posted in private channels the bot is a member of
    • message.mpim - Messages posted in multi-person direct messages the bot is a member of
    • app_mention - When someone @mentions your bot in a channel or group DM
  3. Click Save Changes
The message.im event is required for direct message support. The remaining events (message.channels, message.groups, message.mpim, and app_mention) are required for channel and group DM support. If you only need direct message interactions, you can subscribe to message.im alone.

​
Testing Your Slack Bot

Your Slack bot is now fully configured and ready to use:
  1. The bot will appear in your Slack workspace under Apps
  2. Send a direct message to the bot
  3. The message should be received by your Airia agent
  4. You should receive a response from the agent through the bot
Start by testing your bot with a simple direct message before adding it to channels. Monitor the Conversation Feed in Airia to troubleshoot any issues.

​
User Mapping (For “Existing Airia User” Mode)

If you selected “Existing Airia User” as your execution configuration, Airia will automatically map Slack users to Airia users based on email addresses.

​
How Automatic Mapping Works

Airia automatically matches Slack users to Airia users when:
  • Both the Slack account and Airia account use the same email address
  • The users:read.email scope is granted to your Slack app (required)
When a user sends a message to the bot:
  1. Airia retrieves the user’s email from Slack using the bot’s permissions
  2. Searches for an Airia user with a matching email address
  3. Executes the agent with that Airia user’s permissions and context
If a Slack user cannot be matched to an Airia user (no matching email), they will not be able to interact with the bot when using “Existing Airia User” mode. Ensure your users have Airia accounts with email addresses matching their Slack profiles.

​
Using Your Slack Bot

Once deployed, users can interact with your agent through direct messages, channel @mentions, and group DMs.

​
Direct Messages

Users can send direct messages to the bot for one-on-one interactions:
  1. Find the bot in the Slack sidebar under Apps
  2. Click to open a direct message conversation
  3. Type a message and send
  4. The bot will respond directly in the conversation

​
Channel and Group DM Interactions

Users can @mention the bot in channels and group DMs:
  1. Add the bot to a public or private channel, or include it in a group DM
  2. @mention the bot followed by your message (e.g., @YourBot what is our refund policy?)
  3. The bot will respond in a thread attached to the mention
  4. Users can continue the conversation by replying in the thread — the bot will respond to all thread replies without requiring another @mention
In channels and group DMs, the bot only responds to @mentions and thread replies to its conversations. It does not respond to every message in the channel. This prevents the bot from being disruptive in busy channels.

​
Slack Context Variables

When your agent is triggered from Slack, the following variables are automatically available during execution. You can reference them in prompts, tool fields, Python code blocks, and agent router steps to build context-aware workflows.
Use slack_channel_id to give your agent awareness of where a conversation is happening. For example, you can instruct your agent to tailor its responses based on whether it’s in a DM (D prefix) or a shared channel (C prefix), or route requests differently depending on the channel.

​
Best Practices

​
Security

  • Webhook URL Protection: Keep your webhook URL secure and don’t share it publicly
  • Scope Minimization: Only request the OAuth scopes your bot actually needs
  • Access Control: Configure your agent’s policies to control what data the bot can access
  • Audit Logs: Regularly review bot activity in Airia’s monitoring feeds
  • Execution Context: Choose the appropriate execution configuration based on your security requirements

​
User Experience

  • Clear Bot Identity: Use a descriptive bot name and profile picture
  • Response Time: Ensure your agent is optimized for quick responses in direct messages
  • Error Handling: Configure graceful error messages when the bot can’t fulfill requests
  • Context Awareness: Enable chat history in your agent’s configuration to maintain conversation context
  • User Guidance: Communicate to users that the bot is available via direct messages

​
Agent Configuration

  • Clear Instructions: Provide clear system prompts that define the bot’s role and capabilities
  • Tool Access: Ensure your agent has access to necessary tools and data sources
  • Rate Limiting: Configure appropriate usage limits to prevent abuse
  • Monitoring: Set up alerts for errors or unusual activity
  • Markdown Compatibility: Slack only supports a subset of markdown (bold, italics, strikethrough, inline code, code blocks, blockquotes, and lists). Since AI agents typically respond in markdown, include a prompt instruction for your agent to avoid using unsupported formatting like tables, nested lists, HTML, or complex markdown syntax. For example, add to your system prompt: “When responding in Slack, use only basic markdown: bold (text), italics (text), strikethrough (text), inline code (code), code blocks (```), blockquotes (>), and simple lists. Do not use tables, nested lists, or HTML formatting.”

​
Use Cases

​
IT Support Bot

Deploy an agent that helps employees with common IT issues via direct messages:
  • Password resets
  • Software troubleshooting
  • Access requests
  • Ticket status lookups
  • IT knowledge base queries

​
HR Assistant

Create a bot that assists with HR-related questions through private conversations:
  • Benefits information
  • PTO policies
  • Onboarding guidance
  • Company policy lookups
  • Personal HR inquiries

​
Personal Productivity Assistant

Build an agent that helps individuals manage their work:
  • Task reminders
  • Meeting preparation
  • Document summarization
  • Quick research queries
  • Personal knowledge management

​
Sales Assistant

Deploy a bot that supports sales team members individually:
  • CRM data lookups
  • Lead qualification
  • Account information
  • Quick competitive intelligence
  • Sales playbook access

​
Troubleshooting

Check the following:
  • Verify the Slack credential in Airia has the correct OAuth token
  • Ensure the webhook URL is correctly configured in your Slack app’s Event Subscriptions
  • Confirm all required OAuth scopes are granted in your Slack app
  • Check that the agent deployment is active in Airia
  • Review error logs in Airia’s monitoring feeds (Conversation Feed)
  • Verify the bot is still installed in your workspace
  • Ensure the required event subscriptions are configured (message.im for DMs; app_mention, message.channels, message.groups, message.mpim for channels and group DMs)
This indicates webhook verification failed:
  • Ensure your Airia deployment is active and saved
  • Copy the webhook URL again from Airia (don’t manually type it)
  • Check that there are no extra spaces or characters when pasting
  • Wait a moment after creating the deployment before verifying in Slack
  • If the issue persists, delete and recreate the deployment in Airia
Slack treats public and private channels as separate resource types, each gated by its own OAuth scopes. If the bot was only granted the public channels:* scopes, private channels are invisible to it — even channels it was explicitly invited to. The agent’s channel lookup returns no match and the send-message call fails with a “channel not found” style error.To resolve:
  • Return to your Slack app’s OAuth & Permissions page
  • Add groups:read, groups:write, and groups:history under Bot Token Scopes
  • Click Reinstall to Workspace to apply the new scopes (existing tokens do not automatically gain new permissions)
  • Make sure the bot has been invited to the private channel with /invite @YourBotName from inside that channel
  • Retry the agent action
Updating the app’s scope list is not enough on its own — Slack only applies new scopes on reinstall/reauth, and the stored credential in Airia will continue to use the old permissions until the app is reinstalled.
This typically indicates missing OAuth scopes:
  • Return to your Slack app’s OAuth & Permissions page
  • Verify all required scopes are present (especially files:read and users:read.email)
  • If you added new scopes, reinstall the app to your workspace
  • The bot should automatically pick up the new permissions after reinstallation
Possible causes:
  • The Slack credential in Airia may have an invalid or expired OAuth token
  • The Slack app may not be properly installed to the workspace
  • The deployment may not be properly saved in Airia
  • Try regenerating the OAuth token in Slack and updating the credential in Airia
  • Check your internet connectivity and Slack workspace status
This may be a permissions or user mapping issue:
  • If using “Existing Airia User” execution mode, verify affected users have an Airia account with the same email as their Slack account
  • Confirm the users:read.email scope is granted to your Slack app
  • Check if affected users have blocked the bot in Slack
  • Review your agent’s policies in Airia for user-level restrictions
  • Ensure the users are members of the workspace
Performance optimization steps:
  • Review your agent’s configuration for inefficient steps
  • Check if external tool integrations are responding slowly
  • Monitor token consumption and rate limits
  • Consider simplifying complex agent workflows
  • Check Airia platform status for any service issues
Bot appearance is managed in Slack:
  • Go to https://api.slack.com/apps
  • Select your app
  • Navigate to Features > App Home
  • Update the Display Name and Bot User Icon
  • Changes appear immediately in your workspace
Yes, but each workspace requires its own Slack app and credential:
  • Create a separate Slack app for each workspace
  • Obtain a unique OAuth token for each app
  • Add each token as a separate credential in Airia
  • Create separate Slack Bot deployments for each workspace
  • Each deployment operates independently
The bot responds to @mentions and thread replies in channels and group DMs. It does not respond to every message — only messages that @mention the bot or replies within an existing bot thread. To use the bot in a channel, add it as a member first. Ensure your Slack app is subscribed to the message.channels, message.groups, message.mpim, and app_mention events.
Enable chat history in your agent:
  • Edit your agent in Airia’s Agent Studio
  • Navigate to AI steps in your agent flow
  • Enable “Include the chat history” option for all LLM steps
  • This allows the agent to reference previous messages in the conversation
Slack only supports a limited subset of markdown, which can cause formatting issues with AI-generated responses:Supported markdown in Slack:
  • Bold: *text*
  • Italics: _text_
  • Strikethrough: ~text~
  • Inline code: `code`
  • Code blocks: ```
  • Blockquotes: >
  • Simple lists (bulleted and numbered)
Not supported by Slack:
  • Tables
  • Nested lists
  • HTML formatting
  • Complex markdown syntax
  • Some heading styles
  • Images embedded in markdown
Solution: Update your agent’s system prompt to instruct it to use only Slack-compatible markdown. Add this to your agent’s system instructions:“When responding in Slack, use only basic markdown: bold (text), italics (text), strikethrough (text), inline code (code), code blocks (```), blockquotes (>), and simple lists. Do not use tables, nested lists, or HTML formatting.”This ensures your agent generates responses that display correctly in Slack without formatting errors.

​
Managing Your Slack Bot

​
Monitoring Activity

Track your bot’s usage and performance:
  1. Navigate to Feeds in Airia
  2. Select Conversation Feed to view bot interactions
  3. Review Token Consumption for usage patterns
  4. Check Agent Executions for performance metrics

​
Updating Configuration

To modify your bot’s behavior:
  1. Edit the agent in Airia’s Agent Studio
  2. Make your changes to prompts, tools, or flow logic
  3. Save the agent
  4. Changes take effect immediately for new conversations
To modify deployment settings:
  1. Navigate to the Interfaces section in Agent Settings
  2. Click on your Slack Bot deployment
  3. Update execution configuration or other settings
  4. Click Done to save changes

​
Updating OAuth Token

If your OAuth token needs to be regenerated or updated:
  1. Go to https://api.slack.com/apps and select your app
  2. Navigate to OAuth & Permissions
  3. If needed, click Revoke and then Reinstall App to Workspace to get a new token
  4. Copy the new Bot User OAuth Token
  5. In Airia, navigate to Settings > Credentials
  6. Find your Slack credential and update it with the new token
  7. Your deployments will automatically use the updated credential

​
Regenerating Webhook URL

If your webhook URL is compromised or you need a new one:
  1. Navigate to your Slack Bot deployment in Airia
  2. Click Delete to remove the existing deployment
  3. Create a new Slack Bot deployment (you can reuse the same credential)
  4. Copy the new webhook URL
  5. Update the Request URL in your Slack app’s Event Subscriptions

​
Removing the Bot

To deactivate a Slack bot deployment:
  1. In Airia, navigate to your agent’s Interfaces section
  2. Click on the Slack Bot deployment
  3. Click Delete at the bottom of the configuration screen
  4. Confirm the deletion
  5. Optionally, uninstall or delete the Slack app from your workspace at https://api.slack.com/apps

​
Security Considerations

​
Data Privacy

  • Message Content: All messages sent to your bot are processed by your Airia agent
  • Data Retention: Configure data retention settings in Airia’s admin settings
  • Compliance: Ensure your deployment meets your organization’s compliance requirements
  • User Consent: Communicate to users how their messages will be processed

​
Access Control

  • Workspace Membership: Only workspace members can interact with your bot
  • Channel Restrictions: Control which channels the bot can access
  • Policy Enforcement: Use Airia’s policy features to filter sensitive content
  • Role-Based Access: Configure agent-level permissions for different user groups

​
Incident Response

Prepare for security incidents:
  • Quick Deactivation: Know how to quickly delete the deployment in Airia to stop the bot
  • Webhook Security: If webhook URL is exposed, regenerate it immediately
  • Audit Logging: Monitor bot activity in Airia’s Conversation Feed and Agent Executions
  • Incident Procedures: Document steps to disable the bot quickly if needed
  • User Reporting: Provide a way for users to report issues with the bot

​
Support

For additional help with Slack Bot deployment:
  • Review Slack’s API documentation
  • Check Airia’s monitoring feeds for error details
  • Contact your Airia account administrator
  • Reach out to Airia support for platform-specific issues