Slack Integration
Relevant source files
The following files were used as context for generating this wiki page:- apps/api/src/module/slack/slack.module.ts
- apps/api/src/services/slack/slack-bolt.service.ts
- apps/api/src/module/slack/slack.service.ts
- apps/extensions/src/app/services/api/slack.ts
- apps/portal/app/services/api/slack.ts
- apps/portal/components/pagesComponents/integrations/Slack.tsx
- apps/extensions/src/content/panel/screens/imagesScreen/pages/integrations/SlackPage.tsx
- apps/portal/components/shared/SlackChannelModal.tsx
- apps/api/package.json
The Slack integration for Ever Rec allows users to connect their Slack workspace to the platform, enabling them to share screen captures and recordings directly to Slack channels and users. The integration is built using the @slack/bolt library and follows the standard Slack OAuth 2.0 flow for authorization.
Once connected, users can fetch a list of their channels and post messages containing images or videos. The backend API handles token management, message formatting, and interaction with the Slack API, while the frontend provides the user interface for connecting, disconnecting, and sharing content.
Architecture Overview
The integration's architecture spans both the frontend (Portal and Extension) and the backend API. The backend SlackModule orchestrates the logic, with the SlackBoltService acting as a direct wrapper for the Slack API. User tokens and integration status are stored in Firebase Realtime Database.
This diagram shows the high-level interaction between the system components.
Core Components
The backend functionality is encapsulated within the SlackModule.
| Component | Description | File |
|---|---|---|
SlackModule | A NestJS module that imports necessary dependencies and registers providers (SlackService, SlackBoltService) and the controller (SlackController). | apps/api/src/module/slack/slack.module.ts |
SlackController | Exposes the HTTP endpoints for the Slack integration, such as generating a login URL, handling the OAuth callback, posting messages, and disconnecting. It is not present in the provided files but its existence is inferred from the module and service. | apps/api/src/module/slack/slack.controller.ts (Inferred) |
SlackService | Contains the core business logic. It handles storing installation information, fetching channel lists, constructing and posting messages, and managing user disconnection. It interacts with SlackBoltService and Firebase. | apps/api/src/module/slack/slack.service.ts |
SlackBoltService | A wrapper service for the @slack/bolt library. It is responsible for direct communication with the Slack API for tasks like OAuth token exchange, fetching channel lists, posting messages, and uninstalling the app. | apps/api/src/services/slack/slack-bolt.service.ts |
Sources: apps/api/src/module/slack/slack.module.ts:1-23, apps/api/src/module/slack/slack.service.ts:1-320, apps/api/src/services/slack/slack-bolt.service.ts:1-158
Configuration
The SlackBoltService is configured using environment variables, which are accessed via NestJS's ConfigService.
| Variable | Description |
|---|---|
SLACK_CLIENT_ID | The client ID of the Slack app. |
SLACK_CLIENT_SECRET | The client secret of the Slack app. |
SLACK_SIGNING_SECRET | The signing secret used to verify requests from Slack. |
API_BASE_URL | The base URL of the backend API, used to construct the OAuth redirect URI. |
Sources: apps/api/src/services/slack/slack-bolt.service.ts:19-26
User Data Model
When a user successfully integrates their Slack account, specific fields are added to their user record in the Firebase Realtime Database under the path users/{uid}.
This diagram illustrates the fields related to Slack integration within the user's data structure.
slackToken: The user-specific access token (authed_user.access_token) obtained from Slack OAuth. Used for actions on behalf of the user, like posting messages.isSlackIntegrate: A boolean flag set totrueupon successful integration.slackBotToken: The bot access token (access_token) for the workspace. Used for administrative actions like uninstalling the app.
Sources: apps/api/src/module/slack/slack.service.ts:40-44, apps/api/src/module/slack/slack.service.ts:251-255
Key Workflows
Connecting a Slack Account (OAuth2 Flow)
The connection process follows the standard Slack OAuth 2.0 flow, using the user's unique ID (uid) as the state parameter to link the Slack authorization back to the correct user account.
The following sequence diagram details the authorization flow.
Sharing Content to Slack
Once connected, a user can share an image or video to a Slack channel. The backend retrieves the media, generates a public share link if one doesn't exist, and constructs a message using Slack's Block Kit format.
The sequence diagram below outlines the message posting process.
Disconnecting a Slack Account
Users can disconnect their Slack integration from the settings page. This action revokes the stored tokens and updates the user's status in Firebase.
This flowchart shows the disconnection process.
API Endpoints
The Slack integration is managed through a set of RESTful endpoints defined in the SlackController.
| Method | Endpoint | Description | Service Method |
|---|---|---|---|
GET | /api/v1/slack/login-url | Generates and returns the Slack OAuth2 authorization URL. | getSlackLoginUrl |
GET | /api/v1/slack/installation | The OAuth2 redirect URI. Handles the code exchange and stores tokens. | storeInstallationInformation |
GET | /api/v1/slack/channel-list | Fetches a list of the authenticated user's public channels and other users for DMs. | getChannelList |
POST | /api/v1/slack/post-message | Posts a message (image or video) to a specified channel. | slackPostMessage |
POST | /api/v1/slack/disconnect | Disconnects the user's Slack account and revokes tokens. | disconnectUser |
Sources: apps/api/src/module/slack/slack.service.ts, apps/extensions/src/app/services/api/slack.ts, apps/portal/app/services/api/slack.ts
Frontend Integration
The frontend integration is handled by React components in both the portal and extensions applications.
- Connection Management: Components like
SlackPage.tsxandSlack.tsxprovide the UI for users to connect or disconnect their Slack account. They callgetSlackLoginUrl()to initiate the OAuth flow anddisconnectSlackUser()to de-authorize the integration. - Sharing Modal: The
SlackChannelModal.tsxcomponent is used when a user decides to share content. It fetches the list of available channels viagetChannels()and, upon submission, callssendSlackPostMessage()to send the content to the selected channel.
API communication from the frontend is abstracted into service files (apps/extensions/src/app/services/api/slack.ts and apps/portal/app/services/api/slack.ts), which make the actual HTTP requests to the backend.
Sources: apps/portal/components/pagesComponents/integrations/Slack.tsx, apps/extensions/src/content/panel/screens/imagesScreen/pages/integrations/SlackPage.tsx, apps/portal/components/shared/SlackChannelModal.tsx, apps/extensions/src/app/services/api/slack.ts
Conclusion
The Ever Rec Slack integration provides a seamless way for users to share their created content. It leverages the @slack/bolt library for robust interaction with the Slack API and uses a standard OAuth2 flow for secure authorization. The architecture is cleanly divided between frontend concerns and backend logic, with Firebase acting as the persistent store for user integration details.