Docs
Integrations
Slack Integration

Slack Integration

AgenticAnts provides a powerful Slack integration that enables real-time notifications and alerts for your AI agent operations. Get instant updates about critical errors, anomalies, prompt changes, and other important events directly in your Slack workspace.

Overview

The Slack integration allows you to:

  • Receive real-time alerts about critical errors and anomalies
  • Get notified when prompts are edited or created
  • Jump directly from Slack messages to specific prompts in AgenticAnts
  • Configure different notification channels per project
  • Send test messages to verify your integration
  • Customize notification preferences and filters

Features

Real-time Notifications

Stay informed with instant Slack notifications for:

  • Critical Errors: Get alerted when AI agents encounter errors
  • Anomalies: Receive notifications for unusual behavior or performance issues
  • Prompt Changes: Track when prompts are modified or created
  • Cost Alerts: Monitor when spending thresholds are exceeded
  • Performance Issues: Get notified of latency spikes or failures

Channel Configuration

  • Set up different notification channels for different event types
  • Configure per-project Slack channels
  • Route specific agent notifications to dedicated channels
  • Support for both public and private channels

Rich Message Format

Slack messages include:

  • Direct Links: Jump straight to the relevant resource in AgenticAnts
  • Contextual Information: See key metrics and details at a glance
  • Action Buttons: Quick actions directly from Slack
  • Threaded Discussions: Keep conversations organized

Setup

Prerequisites

  • A Slack workspace where you can install apps
  • Workspace admin permissions (or ability to request app installation)
  • AgenticAnts project with admin access

Local Development Setup

If you're setting up the integration for local development, you'll need additional tools:

  • Node.js and pnpm installed
  • macOS (for mkcert) or equivalent SSL certificate tool
  • HTTPS enabled for OAuth callback

Creating a Slack App

  1. Go to Slack API Apps page (opens in a new tab)
  2. Click Create New App → From an app manifest
  3. Select your workspace
  4. Use the following app manifest as a template:
display_information:
  name: AgenticAnts
  description: AI Agent Observability and Monitoring
  background_color: "#2563eb"
features:
  bot_user:
    display_name: AgenticAnts
    always_online: true
oauth_config:
  scopes:
    bot:
      - chat:write
      - chat:write.public
      - channels:read
      - groups:read
      - im:read
      - mpim:read
settings:
  org_deploy_enabled: false
  socket_mode_enabled: false
  token_rotation_enabled: false
  1. Click Create to create your app

Adding App Icon (Optional)

Make your app more recognizable:

  1. In your Slack app settings, go to Basic Information
  2. Scroll to Display Information
  3. Upload the AgenticAnts logo as your app's avatar
  4. Save changes

Environment Variables

Configure your AgenticAnts environment:

  1. In your Slack app settings, go to Basic Information
  2. Copy the Client ID and Client Secret
  3. Add these to your .env file:
SLACK_CLIENT_ID=your_client_id_here
SLACK_CLIENT_SECRET=your_client_secret_here

HTTPS Setup for Local Development

The Slack OAuth flow requires HTTPS. For local development:

macOS Setup

# Install mkcert
brew install mkcert
 
# Install the local CA
mkcert -install
 
# Generate certificates for localhost
mkcert localhost 127.0.0.1
 
# Move certificates to web directory
mv localhost+1*.pem web/

Windows Setup

# Install chocolatey if not already installed
# Then install mkcert
choco install mkcert
 
# Install the local CA
mkcert -install
 
# Generate certificates
mkcert localhost 127.0.0.1
 
# Move certificates to web directory
move localhost+1*.pem web\

Linux Setup

# Install mkcert
# For Ubuntu/Debian
sudo apt install mkcert
 
# For other distributions, use appropriate package manager
 
# Install the local CA
mkcert -install
 
# Generate certificates
mkcert localhost 127.0.0.1
 
# Move certificates to web directory
mv localhost+1*.pem web/

Starting Development Server

From the repository root, run:

pnpm run dev:https

This starts the Next.js development server with HTTPS enabled on https://localhost:3000.

Configuring OAuth Redirect URLs

  1. In your Slack app settings, go to OAuth & Permissions
  2. Under Redirect URLs, add:
    • Development: https://localhost:3000/api/public/slack/oauth
    • Production: https://yourdomain.com/api/public/slack/oauth
  3. Save URLs

Configuration

Connecting to Slack

  1. Navigate to your AgenticAnts project settings
  2. Go to the Integrations tab
  3. Find the Slack integration section
  4. Click Connect to Slack
  5. Authorize the app in your Slack workspace:
    • Review the permissions requested
    • Select the workspace to install to
    • Click Allow
  6. You'll be redirected back to AgenticAnts
  7. Select the default notification channel

Channel Selection

After connecting, configure your notification channels:

  1. Choose a default channel for general notifications
  2. Optionally configure specific channels for:
    • Error alerts
    • Prompt notifications
    • Cost alerts
    • Performance monitoring
  3. Test the connection using the Send Test Message button

Notification Preferences

Customize what notifications you receive:

// Configure in project settings
{
  "slack": {
    "enabled": true,
    "channels": {
      "default": "#agenticants-alerts",
      "errors": "#agenticants-errors",
      "prompts": "#agenticants-prompts",
      "costs": "#agenticants-costs"
    },
    "filters": {
      "minSeverity": "warning",
      "includeEvents": ["error", "prompt_change", "cost_alert"],
      "excludeAgents": ["test-agent"]
    }
  }
}

Usage

Receiving Notifications

Once configured, you'll automatically receive Slack notifications for enabled events.

Example error notification:

🚨 Critical Error in Production Agent

Agent: customer-support-bot
Error: OpenAI API timeout after 30s
Timestamp: 2024-01-15 14:32:15 UTC
Trace ID: trace_abc123

View Details → https://app.agenticants.ai/traces/trace_abc123

Example prompt change notification:

📝 Prompt Updated

Prompt: customer-greeting-v2
Changed by: alice@company.com
Changes: Temperature increased from 0.7 to 0.9
Version: v2.1.0

View Prompt → https://app.agenticants.ai/prompts/prompt_xyz789

Sending Test Messages

Verify your integration is working:

  1. Go to project settings → Integrations → Slack
  2. Click Send Test Message
  3. Check your configured Slack channel for the test message
  4. If successful, you'll see a confirmation in AgenticAnts

Manual Notifications

Send custom notifications via API:

// Using the AgenticAnts SDK
import { AgenticAnts } from '@agenticants/sdk'
 
const ants = new AgenticAnts({ apiKey: process.env.AGENTICANTS_API_KEY })
 
await ants.slack.sendMessage({
  projectId: 'project_123',
  channel: '#alerts',
  text: 'Custom notification message',
  blocks: [
    {
      type: 'section',
      text: {
        type: 'mrkdwn',
        text: '*Important Alert*\nSomething happened!'
      }
    }
  ]
})

API Reference

API Endpoints

GET /api/public/slack/install

Initiates the Slack OAuth installation flow.

Query Parameters:

  • projectId: AgenticAnts project ID

Response: Redirects to Slack authorization page

GET /api/public/slack/oauth

Handles Slack OAuth callback and stores integration details.

Query Parameters:

  • code: OAuth authorization code
  • state: Security state token (contains projectId)

Response:

{
  "success": true,
  "team_id": "T1234567890",
  "channel_id": "C9876543210"
}

Components

SlackConnectionCard

Displays connection status and provides connect/disconnect actions.

import { SlackConnectionCard } from '@/src/features/slack/components/SlackConnectionCard'
 
<SlackConnectionCard projectId={projectId} />

SlackChannelSelector

Allows selection of Slack channels for notifications.

import { SlackChannelSelector } from '@/src/features/slack/components/SlackChannelSelector'
 
<SlackChannelSelector
  projectId={projectId}
  onChannelSelect={handleChannelSelect}
/>

SlackTestButton

Sends a test message to verify the integration.

import { SlackTestButton } from '@/src/features/slack/components/SlackTestButton'
 
<SlackTestButton
  projectId={projectId}
  channelId={channelId}
/>

Server Services

SlackService

Main service for Slack integration operations:

class SlackService {
  // Send a message to Slack
  async sendMessage(config: SlackMessageConfig): Promise<void>
 
  // Get workspace channels
  async getChannels(teamId: string): Promise<SlackChannel[]>
 
  // Store integration details
  async storeIntegration(projectId: string, config: SlackConfig): Promise<void>
 
  // Retrieve integration details
  async getIntegration(projectId: string): Promise<SlackIntegration | null>
 
  // Remove integration
  async deleteIntegration(projectId: string): Promise<void>
 
  // Send test message
  async sendTestMessage(projectId: string, channelId: string): Promise<boolean>
}

TRPC Routes

slack.getIntegrationStatus

Returns the current connection status for a project.

const status = await trpc.slack.getIntegrationStatus.query({ projectId })
// Returns: { connected: boolean, teamName?: string, channelId?: string }

slack.getChannels

Fetches available Slack channels for the connected workspace.

const channels = await trpc.slack.getChannels.query({ projectId })
// Returns: SlackChannel[]

slack.disconnect

Disconnects the Slack integration for a project.

await trpc.slack.disconnect.mutate({ projectId })

slack.sendTestMessage

Sends a test message to verify the integration.

const result = await trpc.slack.sendTestMessage.mutate({
  projectId,
  channelId: 'C1234567890'
})
// Returns: { success: boolean }

Message Templates

Error Alert Template

{
  blocks: [
    {
      type: 'header',
      text: {
        type: 'plain_text',
        text: '🚨 Critical Error',
        emoji: true
      }
    },
    {
      type: 'section',
      fields: [
        { type: 'mrkdwn', text: `*Agent:*\n${agentName}` },
        { type: 'mrkdwn', text: `*Error:*\n${errorMessage}` },
        { type: 'mrkdwn', text: `*Timestamp:*\n${timestamp}` },
        { type: 'mrkdwn', text: `*Trace ID:*\n${traceId}` }
      ]
    },
    {
      type: 'actions',
      elements: [
        {
          type: 'button',
          text: { type: 'plain_text', text: 'View Details' },
          url: `https://app.agenticants.ai/traces/${traceId}`,
          style: 'primary'
        }
      ]
    }
  ]
}

Prompt Change Template

{
  blocks: [
    {
      type: 'header',
      text: {
        type: 'plain_text',
        text: '📝 Prompt Updated',
        emoji: true
      }
    },
    {
      type: 'section',
      fields: [
        { type: 'mrkdwn', text: `*Prompt:*\n${promptName}` },
        { type: 'mrkdwn', text: `*Changed by:*\n${userName}` },
        { type: 'mrkdwn', text: `*Version:*\n${version}` }
      ]
    },
    {
      type: 'section',
      text: {
        type: 'mrkdwn',
        text: `*Changes:*\n${changes}`
      }
    },
    {
      type: 'actions',
      elements: [
        {
          type: 'button',
          text: { type: 'plain_text', text: 'View Prompt' },
          url: `https://app.agenticants.ai/prompts/${promptId}`
        }
      ]
    }
  ]
}

Best Practices

Channel Organization

  • Separate channels by severity: Use different channels for errors vs. informational updates
  • Per-environment channels: Create separate channels for dev, staging, and production
  • Team-specific channels: Route notifications to relevant team channels
  • Use threads: Enable threaded replies to keep channels organized

Notification Management

  • Filter noise: Only enable notifications for actionable events
  • Set severity thresholds: Avoid alert fatigue by focusing on critical issues
  • Use digest mode: For high-volume events, consider daily/weekly summaries
  • Mute during maintenance: Temporarily disable notifications during planned downtime

Security

  • Rotate tokens regularly: Update OAuth tokens every 90 days
  • Limit channel access: Use private channels for sensitive notifications
  • Review permissions: Regularly audit what the bot can access
  • Monitor usage: Check Slack app audit logs for suspicious activity

Troubleshooting

Common Issues

"Invalid redirect URI" error

  • Ensure your Slack app's OAuth redirect URLs include the correct callback URL
  • Check that you're using HTTPS (required for OAuth)
  • Verify the domain matches exactly (including port for local development)

Certificate errors during local development

  • Make sure you've run mkcert -install to install the local CA
  • Try accessing https://localhost:3000 directly and accepting the certificate
  • Restart your development server after generating certificates
  • Check that certificate files are in the correct location

Messages not appearing in Slack

  • Verify the bot is added to the target channel (/invite @AgenticAnts)
  • Check that the channel ID is correct
  • Ensure the bot has chat:write permission
  • Test with a public channel first before trying private channels

"Not authenticated" error

  • Re-authenticate the Slack integration in project settings
  • Verify your OAuth tokens haven't expired
  • Check that the Slack app is still installed in your workspace

Test message fails

  • Confirm the integration is properly connected
  • Check that the selected channel still exists
  • Verify the bot has permissions to post in the channel
  • Review server logs for detailed error messages

Debug Mode

Enable debug logging for Slack integration:

# In your .env file
DEBUG=agenticants:slack:*
LOG_LEVEL=debug

View logs:

# Server logs
tail -f logs/slack-integration.log
 
# Filter for Slack-specific entries
grep "SLACK" logs/server.log

Production Deployment

Pre-deployment Checklist

  • Update OAuth redirect URLs to include production domain
  • Set up proper SSL certificates for production environment
  • Configure environment variables in production
  • Test the integration in staging environment
  • Document the Slack app installation for your team
  • Set up monitoring for Slack API usage
  • Configure rate limiting to avoid API quotas

Scaling Considerations

  • Rate Limits: Slack has rate limits (~1 message per second per channel)
  • Batch Messages: Group related notifications when possible
  • Queue System: Use a message queue for high-volume notifications
  • Retry Logic: Implement exponential backoff for failed messages
  • Circuit Breaker: Disable integration temporarily if Slack is down

Future Enhancements

Planned features for future releases:

  • Interactive Actions: Respond to alerts directly from Slack
  • Slash Commands: Query AgenticAnts data from Slack (/agenticants status)
  • Scheduled Reports: Daily/weekly summaries sent to Slack
  • Thread Management: Automatic threading for related events
  • @mentions: Mention specific team members in notifications
  • Custom Workflows: Build custom notification workflows
  • Bi-directional Sync: Create tickets/tasks from Slack messages
  • Voice Alerts: Integration with Slack voice channels

Support

Need help with the Slack integration?

For enterprise customers:

  • Dedicated Support: Direct access to our integration specialists
  • Custom Setup: We'll help configure your Slack workspace
  • Training: Onboarding sessions for your team

Related Resources

Ready to connect Slack? Head to your project settings and get started!

JIRA IntegrationOverview