Sync with Slack
Slack sync maps a Slack channel to a board channel. Each message posted there is a thread on the board and its thread replies are replies; edits, deletes, and reactions follow. What’s written on the board in those threads goes back to Slack as the bot, in the same Slack thread.
import { defineWorkbus, slackProvider, type Secret } from 'workbus'import type { GatewayEnv } from 'workbus/gateway/gateway.ts'
type Env = GatewayEnv & { MAILBOX: DurableObjectNamespace; SLACK_SIGNING_SECRET: Secret; SLACK_BOT_TOKEN: Secret; SLACK_BOT_USER_ID: string }
export const { Ledger, Relay, Mailbox, Inbox, Workbus, BoardSession, gateway } = defineWorkbus<Env>((env) => ({ sync: { slack: slackProvider({ signingSecret: env.SLACK_SIGNING_SECRET, botToken: env.SLACK_BOT_TOKEN, // Each Slack channel ID, and the board channel its threads come into. channels: { C0SYNCED: 'slack/general' }, // The bot's own user ID: Slack's echo of what the board posted isn't imported again. botUserId: env.SLACK_BOT_USER_ID, }), },}))
export default { fetch: (request: Request, env: Env) => gateway(request, env) }A Slack thread, as it lands on the board (from the provider check: Ada’s message, Bo’s edited reply with Ada’s reaction, and a reply Ada deleted):
{ "id": "2", "by": "Ada (slack:user:U0ADA)", "text": "Deploys to *staging* fail since [run 7](https://ci.test/run/7) & I cannot see why", "origin": "slack:C0SYNCED:1700000000.000100 / 1700000000.000100"}{ "id": "4", "by": "Bo (slack:user:U0BO)", "text": "@[slack:user:U0ADA] looks like the deploy token expired yesterday", "edited": true, "reactions": { "thumbs_up": [ "slack:user:U0ADA" ] }, "origin": "slack:C0SYNCED:1700000000.000100 / 1700000001.000200"}Set it up
Section titled “Set it up”-
Make the Slack app. At api.slack.com/apps, create an app from a manifest, with these bot scopes and no event subscriptions yet: Slack checks a request URL as soon as it’s saved, and the board can answer that check only once it has the app’s signing secret (step 4).
manifest.json {"display_information": { "name": "Workbus sync" },"features": { "bot_user": { "display_name": "workbus", "always_online": true } },"oauth_config": {"scopes": {"bot": ["chat:write", "channels:history", "groups:history", "reactions:read", "reactions:write", "users:read"]}},"settings": {"org_deploy_enabled": false,"socket_mode_enabled": false,"token_rotation_enabled": false}} -
Install it and invite the bot. Install the app to the workspace, and
/invitethe bot into each channel you sync. Note the channel’s ID (in the channel’s details) and the bot’s user ID. -
Give the Worker the app’s secrets. The signing secret is on the app’s Basic Information page, and the bot token (
xoxb-…) on OAuth & Permissions. Store them in your account’s Secrets Store:Terminal window # your store's ID, from: npx wrangler secrets-store store listnpx wrangler secrets-store secret create <store id> --name slack-signing-secret --scopes workers --remotenpx wrangler secrets-store secret create <store id> --name slack-bot-token --scopes workers --remoteand bind them:
wrangler.jsonc "secrets_store_secrets": [{ "binding": "SLACK_SIGNING_SECRET", "store_id": "<store id>", "secret_name": "slack-signing-secret" },{ "binding": "SLACK_BOT_TOKEN", "store_id": "<store id>", "secret_name": "slack-bot-token" }],"vars": { "SLACK_BOT_USER_ID": "U0BOT" }Plain Worker secrets (
wrangler secret put SLACK_SIGNING_SECRET) work as well: the provider reads either. -
Deploy, then turn on events.
npx wrangler deploy. Then, on the app’s Event Subscriptions page, turn events on with your board’s webhook route as the request URL,https://<your worker>/b/<board>/webhooks/slack. Slack shows Verified once the board answers its challenge, signed with the secret from step 3. Subscribe to the bot eventsmessage.channels,message.groups,reaction_added, andreaction_removed, and save; reinstall the app if Slack asks. Post in the channel, andwb tail slack/general.
What comes in
Section titled “What comes in”| In Slack | On the board |
|---|---|
| a message in a mapped channel | a thread in its board channel |
| a reply in its Slack thread | a reply |
| an edit, a delete | the board message edited, or deleted (a root deleted under replies stays as a tombstone) |
| a reaction added or removed | the reaction added or removed |
Each message is by its Slack author, slack:user:<id>, named from users.info. Slack’s mrkdwn becomes the board’s markdown: links become [text](url), a mention of a person becomes @[slack:user:<id>], and <, >, and & become their characters. Channels you didn’t map, joins, and changes that leave the text as it was (a reply count, an unfurl) are kept as nothing. Requests older than 5 minutes, or not signed with the app’s signing secret, answer 401:
# slack: verificationurl_verification 200 c-3x4mpl3ok url_verification answers its challengebad signature 401 not signed by this app6 minutes old 401 too old, or no timestampok a forged or stale request is 401What goes back
Section titled “What goes back”A message written on the board in a synced thread is posted with chat.postMessage in that Slack thread, as the bot. Editing it calls chat.update, deleting it chat.delete, and a reaction reactions.add or reactions.remove. A board thread sent to a Slack channel ("sync": ["slack:C0SYNCED"] on the post) starts a Slack thread there.
board reply #12slack got POST /slack/api/chat.postMessage auth=Bearer xoxb-test {"channel":"C0SYNCED","thread_ts":"1700000000.000100","text":"Rotated the deploy token: <staging> & prod should go green now"} -> ts 1700000900.000100ok one chat.postMessage, in the root's thread, with the bot token from Secrets Storeok the receipt records the ts Slack answeredSlack sends the bot’s own message back as an event, sometimes before chat.postMessage has answered. With botUserId (and botId, if the app posts as a bot ID), that echo waits for the courier’s receipt and then lands as nothing, so the reply is on the board once. The bot’s own reactions are dropped the same way.
Check it locally
Section titled “Check it locally”test/providers-worker is a Worker with Slack and Linear as its own syncs, credentials in a local Secrets Store, and each platform’s API pointed at a mock. check.mjs signs every request as Slack and Linear sign them, sends each delivery twice, and reads the board back. From packages/workbus (the values are test values; the check is told the same ones):
cd test/providers-workernpx wrangler secrets-store secret create 0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f --name slack-signing-secret --value slack-test-secret --scopes workers --persist-to /tmp/providers-statenpx wrangler secrets-store secret create 0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f --name slack-bot-token --value xoxb-test --scopes workers --persist-to /tmp/providers-state# an env file with BOARD_ISSUER_KEY (from ../../.dev.vars), LINEAR_WEBHOOK_SECRET, and LINEAR_API_KEYnpx wrangler dev --port 8813 --ip 127.0.0.1 --persist-to /tmp/providers-state --env-file providers.env# in packages/workbus, in a second terminalSLACK_SIGNING_SECRET=slack-test-secret SLACK_BOT_TOKEN=xoxb-test \ LINEAR_WEBHOOK_SECRET=lin-test-secret LINEAR_API_KEY=lin_api_test \ node test/providers-worker/check.mjs# slack: deliveries, each sent twiceroot 200 kept 1 | 200 kept 1reply 200 kept 1 | 200 kept 1reply2 200 kept 1 | 200 kept 1edit 200 kept 1 | 200 kept 1replyCount 200 nothing to keep | 200 nothing to keepreact 200 kept 1 | 200 kept 1reactRoot 200 kept 1 | 200 kept 1unreactRoot 200 kept 1 | 200 kept 1delete 200 kept 1 | 200 kept 1unmapped 200 nothing to keep | 200 nothing to keepjoin 200 nothing to keep | 200 nothing to keep…events in slack/general {"message.posted":3,"message.edited":1,"reaction.added":2,"reaction.removed":1,"message.deleted":1}ok each Slack delivery landed once: 3 posts, 1 edit, 2 reactions added, 1 removed, 1 delete…ok the echo, sent before and after the receipt, imported nothing…all passedAgainst a real workspace, with the credentials in the account’s Secrets Store, a post, a thread reply, its edit, a reaction, and a delete each landed on the board once, and a board reply, its edit, and a reaction each reached Slack.
How it works
Section titled “How it works”Slack’s request goes to the sync’s Inbox, which keeps each event under Slack’s event ID before Slack hears 200, so Slack’s retries do nothing. The Inbox imports one Slack thread at a time, in order, with 5 tries each, and a failed event can be replayed. The courier copies board writes back in each thread’s order. See Sync: Inbox and courier.