Convex Slack

Sync Slack workspaces, channels, messages, and reactions into Convex reactively. Send messages, open modals, and handle slash commands from Convex functions.

convex-slackby sholajegede

Markdown ▾

View Markdown Download MarkdownOpen in ChatGPT ↗Open in Claude ↗Open in Perplexity ↗

For Agents Download Skill

Upstream source

git clone https://github.com/sholajegede/convex-slack.git
cd convex-slack

This upstream package has not been adapted or qualified for Bijection. Read the original documentation before adopting it.

Description

Sync Slack workspaces, channels, messages, and reactions into Convex reactively. Send messages, open modals, and handle slash commands from Convex functions.

Explore the package README for API concepts, configuration, and examples. Check the Bijection source for adaptation-specific setup.

Available to evaluate

Review the source and its dependencies before adopting this package. Source availability does not establish npm publication or runtime qualification.

Getting started

Get the source at the revision above and read its package documentation.
Check the required Bijection SDK version, dependencies, and external service credentials.
Follow the package setup instructions and the guide to using components.
Exercise the component in your deployment according to your project’s verification rules.

Open source

Maintained source: sholajegede/convex-slack. License: See repository. Consult the repository for license terms, notices, and contributor attribution.

From the upstream publisher

Install your app into any number of Slack workspaces, sync channels/messages/reactions/users into Convex reactively, and drive the full Slack platform -- messaging, threads, Block Kit modals, slash commands, shortcuts, and files -- directly from Convex fu

Explore the demo ↗

Upstream overview

From the upstream package documentation.

convex-slack syncs Slack workspaces, channels, messages, reactions, and users into isolated Convex tables via the Slack Events API, enabling reactive queries that update as conversations happen. It handles the full OAuth v2 multi-workspace install flow, cryptographically verifies inbound webhooks, and exposes actions for messaging, Block Kit modals, slash commands, file uploads, and interactivity payloads. Token rotation is handled transparently without additional application code.

Use cases

From the upstream package documentation.

Building a Slack-integrated internal tool where channel messages need to be queryable and reactive in a React frontend without polling
Implementing a multi-workspace Slack app with per-team bot token management and OAuth install flow handled by the backend
Triggering Convex actions in response to slash commands or button clicks, with cryptographically verified payloads logged to queryable tables
Posting automated messages or opening Block Kit modals from Convex mutations or scheduled functions in response to business events
Syncing Slack user and channel data into Convex on demand to power search, filtering, or audit features in your application

How it works

From the upstream package documentation.

Set up starts by registering the component in convex.config.ts via app.use(slack), then instantiating the Slack client with your Slack app credentials. Three signed httpAction handlers (eventsHandler, interactivityHandler, commandsHandler) are mounted on your HTTP router and registered with the corresponding Slack platform endpoints. Every inbound request is verified using Slack's HMAC-SHA256 signing scheme with a 5-minute replay window before any data is written.

Incoming events from the Slack Events API are processed and persisted into isolated tables: messages, reactions, channels, users, interactions, commands, files, and webhookEvents. The webhookEvents table provides idempotency via checkAndRecordEvent, preventing duplicate processing. Messages and reactions are kept current automatically as message, message_changed, message_deleted, reaction_added, and reaction_removed events arrive. Channel and user data is backfilled lazily on first access via calls like listConversationsFromSlack or getUserInfo.

Outbound operations are available as methods on the Slack client instance and are called from Convex actions: postMessage, postEphemeral, updateMessage, deleteMessage, openView, pushView, updateView, publishHomeView, uploadFile, and respondToUrl. All outbound Web API calls include retry logic with exponential backoff and jitter, honoring Slack's Retry-After header on rate limit responses. The component's tables are schema-isolated and only accessible through the functions the component exposes, not through your app's schema directly.

Upstream package FAQ

Does convex-slack require me to manage Slack bot tokens manually?

No. convex-slack stores one bot token per workspace after the OAuth install flow completes. If your Slack app has token rotation enabled, the resolveToken method refreshes and persists the rotated token automatically before it expires. Apps without rotation enabled return the stored token as-is.

Which Slack tables does convex-slack add to my Convex deployment?

convex-slack creates its own isolated schema with these tables: installations, channels, users, messages, reactions, interactions, commands, files, scheduledMessages, and webhookEvents. These tables are not part of your app's schema and are only accessible through the functions the component exposes.

How does convex-slack verify that inbound Slack requests are authentic?

Every Events API, Interactivity, and Slash Command request is verified using Slack's v0=HMAC-SHA256(signingSecret, 'v0:{timestamp}:{body}') scheme before any data is recorded. A 5-minute replay window is enforced to prevent replay attacks. Requests that fail verification are rejected before they reach your handlers.

Which Slack data is synced automatically versus populated on demand?

Messages, reactions, user_change and team_join events, channel create/rename/archive events, and app uninstall or token revocation are all synced automatically as Slack delivers them via the Events API. Channel lists and user records are populated lazily the first time your app calls listConversationsFromSlack, getConversationInfo, getUserInfo, or listUsersFromSlack.

Can convex-slack handle file uploads to Slack?

Yes. convex-slack exposes an uploadFile method that drives the current Slack file upload sequence: files.getUploadURLExternal, uploading the binary content, then files.completeUploadExternal. The deprecated files.upload endpoint is never used. You pass a teamId, filename, Uint8Array content, channelId, and optional initialComment.

Use with agents and CLI

View Skill

Give your coding agent the component’s source identity and setup guidance.

agent-prompt.md

Help me integrate Convex Slack with Bijection.

Read: https://bijection.com/components/convex-slack/SKILL.md

Check SDK compatibility and dependency availability.
Follow this project's execution and verification rules.

Download SKILL.md llms.txt

Upstream README.md

View repository ↗

Documentation from sholajegede/convex-slack, recorded October 23, 2026. APIs and setup may differ in the Bijection adaptation.

What this does

convex-slack gives your Convex app a live, queryable view of every Slack workspace it's installed into, plus a full set of actions for driving the platform — kept in sync by Slack's Events API and interactivity payloads:

Multi-workspace OAuth install — getAuthorizationUrl / exchangeCode implement the full OAuth v2 authorization-code flow, storing one bot token per team_id so a single deployment serves every workspace that installs your app. Token rotation (refresh tokens) is handled transparently: resolveToken refreshes and persists a rotated token automatically before it expires.
Reactive messages, threads, and reactions — message, message_changed, message_deleted, reaction_added, and reaction_removed events keep a messages and reactions table current, so useQuery in your React app re-renders as a conversation happens.
Channels and users, synced on demand — conversations.list/info and users.list/info calls (yours or this component's own) populate channels and users, plus membership/rename/archive events keep them current without a full resync.
Full messaging — postMessage, postEphemeral, updateMessage, deleteMessage, scheduleMessage/deleteScheduledMessage, and addReaction/removeReaction, all callable directly from a Convex action.
Block Kit modals and App Home — openView/pushView/updateView wrap views.open/views.push/views.update for interactive modals, and publishHomeView wraps views.publish for a per-user App Home tab.
Slash commands and interactivity, verified and logged — three signed httpAction handlers (eventsHandler, interactivityHandler, commandsHandler) verify every request against your signing secret before anything is recorded, and every button click, modal submission, shortcut invocation, and slash command is logged to interactions / commands for your own handlers to react to.
Modern file uploads — uploadFile drives the current files.getUploadURLExternal -> upload -> files.completeUploadExternal sequence (the old files.upload is deprecated and never used here).
Resilient Web API calls — every outbound call retries on 429/5xx responses and network failures with exponential backoff and jitter, honoring Slack's Retry-After header (and the JSON-level ratelimited error some methods return).
Cryptographically verified inbound requests — every Events API, Interactivity, and Slash Command delivery is verified against Slack's v0=HMAC-SHA256(signingSecret, "v0:{timestamp}:{body}") scheme, with a 5-minute replay window, before it's trusted.

This is a Convex component: its installations, channels, users, messages, reactions, interactions, commands, files, scheduledMessages, and webhookEvents tables live in an isolated schema, not your app's schema, and are only reachable through the functions this component exposes.