Slack Integration

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• src/slack/slack.controller.ts
• src/slack/slack-events-handler.service.ts
• src/slack/interactions.service.ts
• src/slack/app_home.service.ts
• src/slack/slack.service.ts
• src/database/models/slack-workspace.model.ts
• agent-packages/packages/slack/src/tools.ts
• src/slack/views/app_home.ts
• src/lib/utils/slack.ts
• src/lib/constants.ts
• src/slack/views/modals.ts

The Slack integration is the primary user interface for the Quix AI agent. It allows users to interact with Quix using natural language directly within Slack channels, DMs, and threads. The integration is responsible for handling user messages, app mentions, interactive components (like buttons and modals), and managing the agent's presence and configuration through the App Home tab.

This system serves as the bridge between the Slack platform and the core LLM and integration services of the Quix application. It manages authentication, event handling, user interactions, and presents a rich interface for configuring the agent and its connected tools.

Sources: README.md:3-4, src/slack/slack-events-handler.service.ts, src/slack/interactions.service.ts

Architecture Overview

The Slack integration is built as a module within the main Nest.js application. It exposes endpoints for Slack's Events API and Interactive Components, processes incoming requests, and delegates tasks to various services.

The following diagram illustrates the high-level architecture of the Slack integration and its interaction with other parts of the system.

This diagram shows how user actions in Slack are sent to the SlackController, which routes them to either the SlackEventsHandlerService for events like messages or the InteractionsService for UI interactions. These services then orchestrate responses, often involving the LlmService, AppHomeService, and various integration services.

Sources: src/slack/slack.controller.ts:24-69, src/slack/slack-events-handler.service.ts:32-52, src/slack/interactions.service.ts:27-35

Installation and Configuration

Slack App Manifest

The Slack App is defined by slack_app_manifest.yml. This file specifies the app's name, features, permissions (scopes), and the API endpoints it will use.

Key configuration points in the manifest include:

• Event Subscriptions: The request_url for the Events API is set to <YOUR_EVENTS_URL>, which corresponds to the /slack/events endpoint.
• Interactivity: The request_url for interactive components is set to <YOUR_INTERACTIONS_URL>, corresponding to the /slack/interactions endpoint.
• OAuth & Permissions: The redirect_urls list includes <YOUR_REDIRECT_URL>, which corresponds to the /slack/install endpoint.

Sources: README.md:71-77

Environment Variables

The following environment variables are required for the Slack integration to function:

Variable	Description
SLACK_BOT_TOKEN	The Bot User OAuth Token for the Slack app.
SLACK_SIGNING_SECRET	The Signing Secret to verify requests from Slack.
SLACK_CLIENT_ID	The client ID of the Slack app.
SLACK_CLIENT_SECRET	The client secret of the Slack app.
SELFSERVER_URL	The public base URL of the Quix server, used for OAuth redirects.

Sources: README.md:41-45, src/slack/slack.service.ts:90-94

OAuth Flow

The installation process follows the standard Slack OAuth v2 flow, handled by the SlackService and SlackController.

This sequence shows the user-initiated installation, the exchange of the temporary code for a permanent access_token, and the creation of the SlackWorkspace record in the database.

Sources: src/slack/slack.controller.ts:48-57, src/slack/slack.service.ts:88-141

API Endpoints

The SlackController exposes the necessary endpoints for Slack to communicate with the application.

Method	Path	Description
POST	/slack/events	Handles all incoming events from the Slack Events API, such as messages and app mentions. Verifies the request signature.
POST	/slack/interactions	Handles all interactive component payloads, such as button clicks, modal submissions, and menu selections.
GET	/slack/install	The main OAuth redirect URI for installing the app to a workspace.
GET	/slack/install/:tool	An OAuth redirect URI used when initiating installation for a specific third-party tool (e.g., Jira, GitHub).

Sources: src/slack/slack.controller.ts:24-78

Event Handling

Incoming events from Slack are handled by SlackEventsHandlerService. The main handleEvent method acts as a router based on the event type.

This flow demonstrates how the service first verifies the request, then routes events to specific handlers. For app_mention and message events, it prepares a context for the LLM, processes the message, and sends a reply.

Sources: src/slack/slack-events-handler.service.ts:32-52

Key Event Handlers

• handleAppMention(event): Triggered when the bot is @-mentioned. It adds a reaction (👀), builds the conversation context, calls the LlmService to get a response, and posts the response back to the thread. It also checks if the bot is authorized to respond in that channel.
  Sources: src/slack/slack-events-handler.service.ts:221-262
• handleMessage(event): Handles direct messages to the bot. It ignores messages from other bots or messages without text. It checks if the user is authorized to use Quix, processes the message via the LlmService, and posts a reply.
  Sources: src/slack/slack-events-handler.service.ts:129-192
• handleMemberJoinedChannel(event, teamId): When the bot is added to a channel, it posts a helpful introductory message explaining its capabilities and listing the currently connected integrations.
  Sources: src/slack/slack-events-handler.service.ts:264-325
• handleAppHomeOpened(event, teamId): When a user opens the App Home tab, this triggers the AppHomeService to publish the home view.
  Sources: src/slack/slack-events-handler.service.ts:70-71

Interaction Handling

User interactions with UI elements like buttons, modals, and menus are processed by InteractionsService.

The handleInteraction method routes payloads based on their type.

• block_actions: These are actions originating from interactive blocks within surfaces like App Home or messages (e.g., button clicks, menu selections). If the action is from the App Home, it's passed to AppHomeService.
  Sources: src/slack/interactions.service.ts:37-51
• view_submission: This occurs when a user submits a modal. The service uses a switch statement on the view.callback_id to route the submission to the correct handler, which is often in IntegrationsInstallService or AppHomeService.
  Sources: src/slack/interactions.service.ts:53-277

App Home

The App Home tab, managed by AppHomeService, is the central hub for configuring Quix within Slack. Its view is dynamically generated based on the user's admin status and the workspace's configuration.

Key Features of App Home

• Onboarding View: For new workspaces with no connections, it shows guidance on how to get started and use Quix.
  Sources: src/slack/views/app_home.ts:462-484
• Tool Connection: Admins can see a dropdown to select and configure integrations (e.g., Jira, GitHub, Postgres) or connect to a custom MCP server.
  Sources: src/slack/views/app_home.ts:182-269
• OpenAI Key Management: Admins can add, edit, or remove their OpenAI API key. A trial mode is active for a limited time if no key is set.
  Sources: src/slack/views/app_home.ts:271-303
• Access Controls: Admins can manage which channels Quix can operate in and set permissions for who can interact with the bot in DMs (Everyone vs. Admins Only).
  Sources: src/slack/views/app_home.ts:449-459, src/slack/views/modals.ts:233-288
• Admin Management: Admins can add or remove other users as Quix admins.
  Sources: src/slack/views/app_home.ts:462-472, src/slack/views/modals.ts:139-168
• Non-Admin View: Non-admin users see a restricted view indicating they are not authorized to configure the app.
  Sources: src/slack/views/app_home.ts:438-447

Database Model: SlackWorkspace

The slack_workspaces table is the central model for storing all data related to a single Slack workspace installation.

Sources: src/database/models/slack-workspace.model.ts

Schema Definition

Key Fields and Methods

Field	Type	Description
team_id	string	Primary Key. The Slack workspace's unique ID (e.g., T12345678).
bot_access_token	text	Encrypted Bot User OAuth token (xoxb-...). A getter decrypts it on access.
openai_key	text	Encrypted OpenAI API key provided by the user. A getter provides a default key during the trial period if this is null.
admin_user_ids	string[]	An array of Slack user IDs who are authorized as admins for Quix.
access_settings	jsonb	A JSON object storing access rules, like allowedChannelIds and allowedUsersForDmInteraction.
isTrialMode	boolean	A virtual getter that returns true if no OpenAI key is set and the workspace was created within the trial period (7 days).
isUserAuthorized(userId)	boolean	Helper method to check if a user can interact with the bot based on access_settings.
isChannelAuthorized(channelId)	boolean	Helper method to check if the bot can respond in a given channel.
postMessage(...)	Promise<void>	A convenience method to post a message to a channel using the workspace's bot_access_token.

Sources: src/database/models/slack-workspace.model.ts:31-266

Slack Agent Tools

The Quix agent can use a set of tools to interact with the Slack API itself. These tools are defined in the @clearfeed-ai/quix-slack-agent package and allow the LLM to perform actions like posting messages, listing channels, or adding reactions on behalf of the bot.

Tool Name	Description
slack_list_channels	List public channels in the Slack workspace with pagination.
slack_post_message	Post a new message to a Slack channel.
slack_reply_to_thread	Reply to a specific message thread in Slack.
slack_add_reaction	Add a reaction emoji to a message.
slack_get_channel_history	Get recent messages from a channel.
slack_get_thread_replies	Get all replies in a message thread.
slack_get_users	Get a list of all users in the workspace with their basic profile information.
slack_get_user_profile	Get detailed profile information for a specific user.
slack_join_channel	Join a Slack channel, requires confirmation from the user.
slack_leave_channel	Leave a Slack channel.

Sources: agent-packages/packages/slack/src/tools.ts:40-109

Summary

The Slack integration is a critical component of the Quix platform, providing the entire user-facing experience. It is architected to be robust and extensible, handling a wide range of Slack events and interactions. Through a combination of event-driven services, a dynamic App Home interface, and a well-defined database schema, it enables seamless communication between users, the AI agent, and various integrated business tools. The system is secured through request signature verification and encrypted credentials, ensuring safe and reliable operation within a user's Slack workspace.