> ## Documentation Index
> Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Slack

> Integrate AGO agents with Slack for real-time AI conversations

Integrate AGO with Slack to allow users to interact with AI agents directly from Slack channels with real-time streaming responses.

## Overview

The Slack integration supports:

* Receiving messages from Slack via webhooks
* Message processing by AGO agents
* Real-time response streaming with progressive Slack message updates
* Intelligent caching of Slack users to optimize performance
* Secure authentication and validation of webhooks
* Rich content formatting (images, links, markdown)

## Prerequisites

### System Requirements

* AGO platform deployed and accessible
* Slack workspace with admin permissions

### Knowledge Required

* Slack App configuration basics
* Webhook concepts
* OAuth scopes

### Configuration Required

* Slack App created at api.slack.com
* Bot User OAuth Token obtained
* Event Subscriptions enabled
* "slack" enabled as a message channel in AGO admin settings

> **⚠️ WARNING**: You must enable "slack" as a message channel in the admin settings before webhooks will be processed.

***

## Setup Guide

<Steps>
  <Step title="Create Slack App">
    1. Go to [https://api.slack.com/apps](https://api.slack.com/apps)
    2. Click "Create New App" → "From scratch"
    3. Name your app and select your workspace
  </Step>

  <Step title="Configure OAuth Scopes">
    Navigate to "OAuth & Permissions" and add these Bot Token Scopes:

    | Scope              | Purpose                   |
    | ------------------ | ------------------------- |
    | `chat:write`       | Post messages to channels |
    | `users:read`       | Read user information     |
    | `users:read.email` | Read user email addresses |
  </Step>

  <Step title="Set Up Event Subscriptions">
    Navigate to "Event Subscriptions":

    1. Enable Events: **On**
    2. Request URL: `https://your-domain.com/public/slack/webhook`
    3. Subscribe to bot events:
       * `message.channels`
       * `message.im`

    > **ℹ️ NOTE**: The Request URL will be verified by Slack when you save. Ensure your AGO instance is accessible and the Slack message channel is enabled in admin settings.
  </Step>

  <Step title="Install App">
    1. Go to "Install App" in the sidebar
    2. Click "Install to Workspace"
    3. Copy the **Bot User OAuth Token** (starts with `xoxb-`)
  </Step>

  <Step title="Configure AGO">
    In the AGO admin interface:

    1. Navigate to **Administration > Settings**
    2. In the **Slack** section, enter your **Bot User OAuth Token** (starts with `xoxb-`)
  </Step>
</Steps>

***

## How It Works

When a user sends a message in Slack, AGO receives the event via a webhook, processes the message through the configured AI agent, and streams the response back to Slack with progressive updates. The system handles authentication validation, user lookup and caching, loop prevention, and rich content formatting automatically.

***

## Features

### Real-Time Streaming

AGO responses are streamed to Slack with progressive updates:

1. **Initial message**: "🤔 Thinking..." posted immediately
2. **Periodic updates**: Every 2 seconds during generation
3. **Final message**: Full response once complete

### Rich Content Support

#### Image Support

**Standalone Images** (on their own line):

```markdown theme={null}
![Image description](https://example.com/image.png)
```

Creates a dedicated image block with title and fallback.

**Inline Images** (within text):

```markdown theme={null}
Here's an image ![alt](https://example.com/image.png) in text.
```

Converted to clickable link: `<https://example.com/image.png|alt>`

#### Link Formatting

Markdown links are automatically converted to Slack format:

**Before:** `[our docs](https://docs.example.com)`
**After:** `<https://docs.example.com|our docs>`

#### Markdown Conversion

| Markdown   | Slack Format      |
| ---------- | ----------------- |
| `# Header` | `*Header*` (bold) |
| `- Item`   | `• Item`          |
| `1. Item`  | `• Item`          |

### User Caching

Slack user information is cached for 24 hours:

* **Cache hit**: Immediate response without API call
* **Cache miss/expired**: Calls `users.info` and updates cache
* **Fallback**: Generated email (`slack_{user_id}@unknown.com`) if no email found

### Security Features

| Feature              | Description                                    |
| -------------------- | ---------------------------------------------- |
| Signature validation | HMAC verification of webhooks                  |
| Replay protection    | Timestamp validation (max 5 minutes)           |
| Loop filtering       | Ignores all bot messages                       |
| Event filtering      | Ignores edits, deletions, system notifications |

### Loop Prevention

The system automatically ignores:

* **Bot messages**: Detected via `bot_id`, `subtype: bot_message`, `bot_profile`
* **Our own bot**: Detected using our bot ID via Slack API
* **Edits/deletions**: `message_changed`, `message_deleted`
* **System notifications**: `channel_join`, `channel_leave`, `file_share`
* **Empty messages**: Only whitespace or no content

> **💡 TIP**: Loop filtering prevents infinite response loops when the bot replies to its own messages.

### Event Deduplication

Protection against duplicate messages:

* **`event_id` cache**: Each Slack event has a unique ID
* **1-hour TTL**: Automatic cache cleanup
* **Thread-safe**: Shared cache across processing threads

***

## Agent Targeting

### Query Parameter Targeting

Target a specific agent by adding a query parameter to the webhook URL:

```
https://your-domain.com/public/slack/webhook?agent=<agent_id>
```

**Features:**

* Messages processed by specified agent instead of default
* Fallback to default if agent doesn't exist or user lacks permission
* Different channels can use different agents

**Configuration:**

1. In Slack App Event Subscriptions, use the targeted webhook URL
2. Agent ID must be a valid UUID
3. User must have permission to access the specified agent

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Webhook URL verification fails">
    **Problem**: Slack can't verify the Request URL when setting up Event Subscriptions.

    **Solutions**:

    1. Ensure AGO instance is publicly accessible (not localhost)
    2. Verify "slack" is enabled as a message channel in admin settings
    3. Check server logs for webhook errors
    4. Ensure HTTPS is properly configured
  </Accordion>

  <Accordion title="Bot doesn't respond to messages">
    **Problem**: Messages are sent but no response appears.

    **Solutions**:

    1. Check that the Slack bot token is configured in AGO admin settings
    2. Verify the bot has `chat:write` scope
    3. Ensure the bot is invited to the channel
    4. Check server logs for processing errors
    5. Verify "slack" is enabled as a message channel in admin settings
  </Accordion>

  <Accordion title="&#x22;Thinking...&#x22; message never updates">
    **Problem**: Initial message appears but final response doesn't.

    **Solutions**:

    1. Verify background processing is running
    2. Verify the agent is configured and active
    3. Look for errors in worker logs
    4. Check if knowledge sources are connected
  </Accordion>

  <Accordion title="User emails not captured">
    **Problem**: Slack users show generated emails (`slack_xxx@unknown.com`).

    **Solutions**:

    1. Verify bot has `users:read.email` scope
    2. Check if Slack workspace requires admin approval for email access
    3. Clear user cache and retry
  </Accordion>

  <Accordion title="Duplicate responses">
    **Problem**: Bot responds multiple times to the same message.

    **Solutions**:

    1. Event deduplication should handle this automatically
    2. Check if multiple webhook URLs are configured
    3. Verify only one instance is processing webhooks
  </Accordion>

  <Accordion title="Images not displaying">
    **Problem**: Images show as links instead of embedded images.

    **Solutions**:

    1. Ensure images are on their own line for block display
    2. Verify image URLs are publicly accessible
    3. Check that image URLs use HTTPS
  </Accordion>
</AccordionGroup>

***

## Related Documentation

* [Agents](../agent/agents) - Configure agents for Slack
* [Messenger Integration](./messenger-integration) - Similar chat integration
* [WhatsApp Integration](./whatsapp-integration) - Similar chat integration
* [Widget Authentication](../security/widget-authentication) - Authentication concepts