---
title: "Slack Bot Deployment"
description: "Deploy your Airia agents as Slack bots to enable conversational AI within your workspace."
---

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.

<Note>
Slack Bot deployment requires administrator access to both your Airia account and your Slack workspace.
</Note>

## 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](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

<Tip>
Enabling Agents & AI Apps is required for your bot to properly function within Slack's modern messaging infrastructure.
</Tip>

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

<Note>
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.
</Note>

### 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:

```
assistant:write
chat:write
channels:read
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 channel information
- `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 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

<Warning>
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.
</Warning>

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

<Note>
Slack credentials can be reused across multiple Slack bot deployments in your organization.
</Note>

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

<Tip>
Select "Existing Airia User" for enterprise deployments where you need to maintain user-level permissions and audit trails.
</Tip>

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

<Note>
The webhook URL is unique to this deployment and allows Slack to send events to your Airia agent.
</Note>

## 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](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)

<Warning>
Make sure your Airia deployment is saved before Slack tries to verify the webhook URL, otherwise verification will fail.
</Warning>

### Step 2: Subscribe to Bot Events

1. Scroll down to **Subscribe to bot events**
2. Click **Add Bot User Event** and add:
   - `message.im` - Messages sent to your bot via direct message
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

<Tip>
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.
</Tip>

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

<Warning>
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.
</Warning>

## Using Your Slack Bot

Once deployed, users can interact with your agent through direct messages:

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

<Note>
Currently, Slack bot deployments only support direct message interactions. Channel mentions and slash commands are not yet supported.
</Note>

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

<AccordionGroup>
  <Accordion title="Bot is not responding to messages">
    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 `message.im` event subscription is configured
  </Accordion>

  <Accordion title="Slack says 'Your URL didn't respond with the expected challenge'">
    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
  </Accordion>

  <Accordion title="Bot responds but can't access files or user information">
    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
  </Accordion>

  <Accordion title="Bot doesn't appear online in Slack">
    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
  </Accordion>

  <Accordion title="Bot responds to some users but not others">
    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
  </Accordion>

  <Accordion title="Bot responses are slow or timing out">
    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
  </Accordion>

  <Accordion title="How do I update my bot's name or profile picture?">
    Bot appearance is managed in Slack:
    - Go to [https://api.slack.com/apps](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
  </Accordion>

  <Accordion title="Can I deploy the same agent to multiple Slack workspaces?">
    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
  </Accordion>

  <Accordion title="Can users interact with the bot in channels?">
    Currently, Slack bot deployments only support direct message interactions. Channel mentions, channel messages, and slash commands are not yet supported. Users must send direct messages to the bot to interact with your agent.
  </Accordion>

  <Accordion title="The bot can't maintain conversation context">
    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
  </Accordion>

  <Accordion title="Bot responses show broken formatting or raw markdown">
    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.
  </Accordion>
</AccordionGroup>

## 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](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](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](https://api.slack.com/docs)
- Check Airia's monitoring feeds for error details
- Contact your Airia account administrator
- Reach out to Airia support for platform-specific issues

