Slack Bot Deployment

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.

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: Confirm Socket Mode Is Disabled

Airia receives Slack events over an HTTPS webhook, so Socket Mode must stay off. It is off by default on a new app, but verify it explicitly before configuring anything else:

1. In the left sidebar, navigate to Settings > Socket Mode
2. Confirm that Enable Socket Mode is toggled off
3. If it is on, toggle it off

Step 3: 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

Step 4: 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

Step 5: 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:

assistant:write
chat:write
channels:read
channels:history
groups:read
groups:write
groups:history
mpim:history
im:history
users:read
users:read.email
files:read

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

Step 6: 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 7: 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

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 7 above)
3. This connects your deployment to your Slack workspace using the OAuth token

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

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

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)

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

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

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

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

Slack Context Variables

When your agent is triggered from Slack, the following variables are automatically available during execution. They arrive as input variables, so you reference them through the Variables namespace — {{Variables.slack_channel_id}} — in prompts, tool fields, Python code blocks, and agent router steps to build context-aware workflows.

For example, a prompt can branch on where the conversation is happening:

The current Slack channel is {{Variables.slack_channel_id}} and the
requester is {{Variables.slack_user_id}}. If the channel ID starts with
"D" you are in a private DM, so you may answer in full detail. Otherwise
you are in a shared channel — keep the reply brief and avoid restating
anything sensitive.

See Variables for how these fit alongside the rest of the expression syntax.

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

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 > Ecosystem > 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