--- name: bijection-convex-slack description: "Evaluate and integrate the Convex Slack component with Bijection." --- # Convex Slack Sync Slack workspaces, channels, messages, and reactions into Convex reactively. Send messages, open modals, and handle slash commands from Convex functions. This is an upstream package. It has not been adapted or qualified for Bijection. - Package: convex-slack - Source: https://github.com/sholajegede/convex-slack - npm: https://www.npmjs.com/package/convex-slack - Directory: https://bijection.com/components/convex-slack Read the upstream README for setup, license, and compatibility before using it. ## Integration workflow 1. Read the source README and package manifest at the recorded revision. 2. Confirm the required SDK, dependency availability, and runtime compatibility. 3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name. 4. Keep credentials in the project's existing secret store. 5. Follow the project's execution rules for verification and report what was actually checked. ## Original upstream skill The following guidance describes convex-slack. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately. > Agents: read this skill fully before writing code that uses Convex Slack. Follow the installation and configuration steps exactly. # Convex Slack ## Instructions Use Convex Slack to sync slack workspaces, channels, messages, and reactions into convex reactively, and drive messaging, modals, slash commands, and file uploads from convex functions. This Convex component integrates directly with your backend. ### Installation ```bash npm install convex-slack ``` Current npm version: `convex-slack@0.0.3` ### Capabilities - Query live Slack messages and reactions directly from Convex using useQuery without polling, because Events API payloads sync them automatically. - Handle multi-workspace OAuth installs with built-in token rotation so a single Convex deployment serves every workspace that installs your app. - Send messages, open Block Kit modals, upload files, and respond to slash commands and button clicks from standard Convex actions. - Verify every inbound Slack request cryptographically using HMAC-SHA256 before any data is written, with a 5-minute replay window enforced. ## Examples ### how to sync Slack messages into a database reactively convex-slack registers HTTP action handlers for Slack's Events API that automatically write incoming message, message_changed, message_deleted, reaction_added, and reaction_removed events into isolated Convex tables. Your React app can then call useQuery against listMessagesByChannel and re-render in real time as the conversation happens, with no polling required. ### how to send a Slack message from a Convex function Instantiate the Slack client with your credentials and call slack.postMessage(ctx, { teamId, channel, text }) from a Convex action. The method resolves the stored bot token for that workspace, retries on 429 and 5xx responses with exponential backoff, and honors Slack's Retry-After header automatically. ### how to handle Slack slash commands in a backend convex-slack exposes a commandsHandler HTTP action that verifies the HMAC-SHA256 signature and records each invocation, including the trigger_id, to a commands table. Your own action can then read from that table and call slack.openView within the 3-second trigger_id window to open a Block Kit modal in response. ### multi-workspace Slack OAuth install with token rotation convex-slack implements the full OAuth v2 authorization-code flow via getAuthorizationUrl and exchangeCode, storing one bot token per team_id. If token rotation is enabled on your Slack app, resolveToken automatically refreshes and persists the rotated token pair before expiry, requiring no extra code in your application. ## When NOT to use - When a simpler built-in solution exists for your specific use case - If you are not using Convex as your backend - When the functionality provided by Convex Slack is not needed ## Troubleshooting **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. ## Resources - [npm package](https://www.npmjs.com/package/convex-slack) - [GitHub repository](https://github.com/sholajegede/convex-slack) - [Live demo](https://github.com/sholajegede/convex-slack/tree/main/example) - [Convex Components Directory](https://www.convex.dev/components/convex-slack) - [Convex documentation](https://docs.convex.dev)