Slack Integration

Relevant source files

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

• slack-app/manifest.json
• convex/slack.ts
• convex/slackCommands.ts
• convex/slackAuth.ts
• src/components/SlackSettings.tsx
• convex/http.ts
• convex/schema.ts

The TalkCRM Slack integration allows users to interact with their Salesforce data directly from their Slack workspace. It provides a conversational interface through slash commands and app mentions, enabling users to search for records, view their pipeline, manage tasks, and log activities. The integration also delivers proactive notifications, such as call summaries and deal alerts, to configured Slack channels.

This system is built using a Slack App connected to a Convex backend, which handles OAuth, webhook events, and API calls to Salesforce. A React component in the TalkCRM web application allows users to manage their connection and notification preferences.

Architecture Overview

The integration is centered around the Convex backend, which acts as the intermediary between Slack and Salesforce. All interactions initiated from Slack are sent as webhooks to Convex HTTP endpoints. These endpoints then trigger Convex actions to process the request, interact with the Salesforce API, and send a response back to Slack.

The following diagram illustrates the high-level architecture of the Slack integration.

Data Model

The Slack integration relies on several tables in the Convex database to store installation details, channel configurations, and temporary OAuth states.

The diagram below shows the entity relationships for the Slack data model.

slackInstallations Table

Stores authentication and configuration details for each Slack workspace that installs the app.

Field	Type	Description
userId	Id<"users">	The TalkCRM user who installed the app.
teamId	string	The Slack workspace ID.
teamName	string	The Slack workspace name.
botToken	string	The xoxb-... token for API authentication.
botUserId	string	The bot's user ID in the workspace.
isActive	boolean	true if the installation is active.
Sources: convex/schema.ts:373-388

slackChannelMappings Table

Maps notification types to specific Slack channels for a user.

Field	Type	Description
userId	Id<"users">	The user who configured the mapping.
installationId	Id<"slackInstallations">	The parent installation.
channelId	string	The ID of the Slack channel.
purpose	string	The type of notification (e.g., deal_alerts, call_summaries).
isActive	boolean	true if the mapping is active.
Sources: convex/schema.ts:391-415

slackOAuthStates Table

Temporarily stores state information during the OAuth flow for CSRF protection.

Field	Type	Description
state	string	A unique, random string for CSRF protection.
userId	Id<"users">	The user initiating the OAuth flow.
returnUrl	string	The URL to redirect to after a successful installation.
expiresAt	number	Timestamp when the state expires (10 minutes).
Sources: convex/schema.ts:456-464

Authentication and Installation

Connecting a Slack workspace to TalkCRM uses the standard Slack OAuth 2.0 flow. The process is initiated from the SlackSettings.tsx component in the web app or from the setup wizard in the Salesforce LWC.

OAuth Flow

The sequence diagram below details the installation and authentication process.

Key functions and endpoints:

• GET /api/slack/install: Initiates the flow by generating a state token and redirecting the user to Slack's authorization URL.
• GET /api/slack/oauth/callback: Handles the callback from Slack, exchanges the authorization code for an access token, and saves the installation details.
• createOAuthState / validateOAuthState: Mutations in convex/slackAuth.ts for managing CSRF tokens in the slackOAuthStates table.
• completeOAuthFlow: An internal action that orchestrates token exchange and saving the installation data.
• saveInstallation: An internal mutation that creates or updates a record in the slackInstallations table.

Sources: convex/http.ts:2385-2428, convex/slackAuth.ts:29-82, 115-201, convex/slack.ts:204-245

Features

Slash Commands (/crm)

The primary way users interact with TalkCRM is via the /crm slash command. The app manifest defines this command and points it to a Convex webhook.

• Command: /crm
• Webhook URL: https://<convex-deployment-url>/webhooks/slack/commands
• Description: "Manage your Salesforce CRM"
• Usage Hint: [search|pipeline|tasks|log|help] [query]

Sources: slack-app/manifest.json:17-24

Command Handling Flow

When a user executes a /crm command, Slack sends a POST request to the command webhook. The backend immediately acknowledges the request and schedules a task to process the command asynchronously to avoid Slack's 3-second timeout.

Available Subcommands

Subcommand(s)	Description	Handler Function
search, find, lookup	Searches Salesforce for records matching a query.	handleSearch
pipeline, deals, opportunities	Retrieves the user's sales pipeline from Salesforce.	handlePipeline
tasks, todo, todos	Fetches the user's open or completed tasks.	handleTasks
log, note	Logs a note or activity against a Salesforce record.	handleLog
help or (empty)	Displays a help message with available commands.	handleHelp
(any other text)	The query is passed to an AI for interpretation.	handleAIQuery

Sources: convex/slackCommands.ts:80-101

App Mentions and DMs

Users can also interact with the bot by mentioning it in a channel (@TalkCRM) or sending it a Direct Message. The app is configured to listen to app_mention and message.im events.

• Event Webhook URL: https://<convex-deployment-url>/webhooks/slack/events

When an event is received, the handleAppMention action is triggered. It extracts the user's query from the message text and passes it to the handleAIQuery action for processing by the AI assistant.

Sources: slack-app/manifest.json:38-44, convex/http.ts:2159-2223, convex/slackCommands.ts:384-421

Notifications

TalkCRM can send proactive notifications to Slack for events like a completed call or a deal stage change. This is managed through channel mappings.

Notification Configuration

The SlackSettings.tsx component provides a UI for users to map specific notification types to desired channels.

The available notification purposes are:

• deal_alerts: When deals change stage or are won/lost.
• call_summaries: AI-generated summaries after each TalkCRM call.
• task_reminders: Daily digest of open and overdue tasks.
• all_activity: All CRM updates.

Sources: src/components/SlackSettings.tsx:20-65

Notification Flow

When an event occurs in the application (e.g., a call is completed in convex/http.ts), an internal action like internal.slack.notifyCallCompleted is called. This action constructs a message and uses internal.slack.sendNotification to deliver it. sendNotification looks up the correct channel from the slackChannelMappings table and posts the message using the chat.postMessage API.

Sources: convex/http.ts:1270-1293, convex/slack.ts:488-531, convex/slack.ts:446-485

API Endpoints

The integration exposes several HTTP endpoints in convex/http.ts to handle interactions with Slack and the frontend.

Method	Path	Description
GET	/api/slack/install	Generates a Slack OAuth URL and redirects the user.
GET	/api/slack/oauth/callback	Handles the OAuth callback from Slack after installation.
POST	/webhooks/slack/events	Receives event subscriptions like app_mention and message.im.
POST	/webhooks/slack/commands	Receives slash command invocations.
POST	/webhooks/slack/actions	Receives interactive component payloads (e.g., button clicks).
GET	/api/slack/status	Provides connection status for the frontend UI.
GET	/api/slack/channels	Fetches a list of available channels and current mappings for the UI.
POST	/api/slack/channels	Sets or removes a channel mapping for a notification purpose.
POST	/api/slack/disconnect	Disconnects the user's Slack integration.

Sources: convex/http.ts:2090-2483

Disconnecting Slack

Users can disconnect their Slack integration from the SlackSettings UI. This triggers a POST request to /api/slack/disconnect. The backend disconnectSlack action revokes the Slack API token and marks the slackInstallations and slackChannelMappings records as inactive.

Sources: src/components/SlackSettings.tsx:175-200, convex/http.ts:2456-2483, convex/slackAuth.ts:223-255