Skip to main content
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

1

Create Slack App

  1. Go to https://api.slack.com/apps
  2. Click “Create New App” → “From scratch”
  3. Name your app and select your workspace
2

Configure OAuth Scopes

Navigate to “OAuth & Permissions” and add these Bot Token Scopes:
3

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.
4

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-)
5

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

​
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):
Creates a dedicated image block with title and fallback. Inline Images (within text):
Converted to clickable link: <https://example.com/image.png|alt> Markdown links are automatically converted to Slack format: Before: [our docs](https://docs.example.com) After: <https://docs.example.com|our docs>

​
Markdown Conversion

​
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

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

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