Slack Bot Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Slack Bot Integration provides a robust bridge between the Slack communication platform and the Recoup AI ecosystem. It enables real-time interaction with AI agents directly through Slack channels, supporting features such as automated coding assistance, content generation, and administrative monitoring of bot mentions.
The integration utilizes a unified adapter pattern via the Chat SDK, allowing Slack events (messages, mentions, and interactivity) to be processed by domain-specific handlers. These handlers orchestrate complex tasks, such as triggering background jobs via Trigger.dev and persisting conversation state in Redis, ensuring a seamless experience for music industry professionals collaborating within Slack.
Sources: README.md:126-140, lib/coding-agent/tests/bot.test.ts:44-60
Architecture and Components
The Slack integration is built on a modular architecture that separates platform-specific ingestion from business logic. It consists of three primary layers: the Webhook Layer, the Adapter Layer, and the Task Execution Layer.
Webhook Layer
This layer handles incoming HTTP requests from Slack's Events API and Interactivity services. It includes specialized logic for Slack's url_verification challenge to ensure secure connectivity during initial setup.
Sources: app/api/coding-agent/tests/route.test.ts:31-45, lib/agents/createPlatformRoutes.ts:58-61
Adapter Layer
The system uses the SlackAdapter from the Chat SDK to normalize Slack-specific payloads into a standard format used by the internal AI agents. This adapter manages the connection to Slack using bot tokens and signing secrets.
Sources: lib/coding-agent/tests/bot.test.ts:58-65, README.md:135-138
State Management
Bot state, including thread status and run IDs, is persisted using an ioredis state adapter. This ensures that the bot can maintain context across multiple messages in a Slack thread.
Sources: lib/coding-agent/tests/bot.test.ts:68-75, README.md:143-145
The diagram above illustrates the flow of a message from Slack through the API to a background task and the subsequent response.
Sources: README.md:131-140, app/api/coding-agent/tests/route.test.ts:52-81
Webhook Handling and Route Creation
The project employs a factory pattern to create standardized platform routes. This prevents duplication across different types of bots (e.g., coding-agent, content-agent).
Platform Route Factory
The createPlatformRoutes function generates both GET and POST handlers. It performs several critical steps:
- Validation: Uses Zod to ensure the platform parameter (e.g., "slack") is valid.
- Slack Verification: Specifically intercepts POST requests to handle Slack's URL verification handshake.
- Bot Initialization: Calls
bot.initialize()before delegating the request to the platform-specific webhook handler. - Asynchronous Execution: Uses the Next.js
afterutility to handle background tasks via thewaitUntiloption.
Sources: lib/agents/createPlatformRoutes.ts:25-85
Endpoint Configuration
| Path | Method | Purpose |
|---|---|---|
/api/coding-agent/slack | POST | Main entry point for Slack Events and Interactivity |
/api/coding-agent/callback | POST | Callback URL for Trigger.dev to post results |
Sources: README.md:131-134, README.md:155-157
Mentions and Tags Management
For administrative and monitoring purposes, the system includes a mechanism to fetch and aggregate bot mentions across Slack channels.
Mention Processing Logic
The system retrieves mentions by:
- Identifying the bot's user ID and the channels it belongs to.
- Fetching message history and filtering for messages that explicitly mention the bot.
- Building "Bot Tags" which include user info (name, avatar), the original prompt, and any thread responses.
- Sorting results by timestamp, newest first.
Sources: lib/admins/slack/tests/fetchBotMentions.test.ts:40-75, lib/admins/slack/tests/fetchBotMentions.test.ts:108-125
Handler Factory for Admin Tags
A specialized factory, createSlackTagsHandler, creates endpoints for viewing these mentions. This is used for different domains like coding and content.
The sequence diagram shows the internal process of aggregating Slack mentions for admin dashboards.
Sources: lib/admins/slack/createSlackTagsHandler.ts:24-55, lib/admins/slack/tests/fetchBotMentions.test.ts:43-65
Configuration and Secrets
The Slack integration requires specific environment variables for secure communication and API access.
| Variable Name | Description | Required For |
|---|---|---|
SLACK_BOT_TOKEN | Bot User OAuth Token (xoxb-...) | API calls and Adapter setup |
SLACK_SIGNING_SECRET | Secret used to verify Slack requests | Webhook security |
REDIS_URL | Connection string for state persistence | Thread management |
TRIGGER_CALLBACK_URL | The public URL for task callbacks | Background job completion |
Sources: lib/coding-agent/tests/bot.test.ts:35-40, README.md:162-164
Summary
The Slack Bot Integration is a sophisticated system that enables the Recoup API to interact with users directly within their existing workflows. By utilizing a factory-based route architecture, standardized Chat SDK adapters, and Redis-backed state management, the integration provides a scalable and maintainable way to deploy AI agents across Slack. The inclusion of administrative mention-tracking handlers further allows for oversight and analysis of agent performance.
Sources: README.md:126-145, lib/agents/createPlatformRoutes.ts:25-35