← setup-guides

Slack Integration

Send DMs + channel messages from HiveJournal via a Slack bot — e.g. ad-hoc contributor/ops messages, and (later) auto-notifications like "DM a contributor when their PR merges." Backend: services/slack.ts. CLI: scripts/slack-dm.mjs.

1. Create the Slack app

  1. api.slack.com/apps → Create New App → From scratch → pick your workspace.
  2. OAuth & Permissions → Bot Token Scopes, add:
    • chat:write — send messages
    • users:read.email — resolve a person by their email (so you can DM by email, not just member ID)
    • (optional) channels:read / groups:read if you'll post to channels by #name
  3. Install to Workspace, approve. Copy the Bot User OAuth Token (xoxb-…).
  4. To DM a person, the bot just needs chat:write (it opens a DM via conversations.open). To post to a channel, invite the bot to that channel first (/invite @YourBot).

2. Store the token (it's a secret)

SLACK_BOT_TOKEN=xoxb-…

  • Production → set it in the backend's Railway env.
  • Local → put it in apps/backend/.env (gitignored) and/or export it in your shell to use the CLI script.
  • Never paste it in chat/DM or commit it. If it leaks, rotate it in the Slack app's OAuth & Permissions page. See SECRETS_HANDLING.md.

If SLACK_BOT_TOKEN is unset, the integration is a no-op — nothing breaks, sends just return { ok: false, skipped: true }.

3. Find someone's member ID (optional)

You can DM by email (uses users:read.email) or by member ID. To get a member ID: in Slack, click the person → Profile → ⋮ → Copy member ID (U…).

4. Send

From the CLI (no build step):

export SLACK_BOT_TOKEN=xoxb-…
node scripts/slack-dm.mjs U0123ABCD "hey — pulled latest main?"
node scripts/slack-dm.mjs ryan@example.com "the guide is updated"
node scripts/slack-dm.mjs '#contributors' "new task on the board"

From the app (super-admin) — POST /api/slack/send:

{ "to": "U0123ABCD", "text": "hello" }      // DM a user (member ID or email)
{ "channel": "#contributors", "text": "…" } // or post to a channel

GET /api/slack/status → { enabled: <bool> }.

From code — import { sendSlackDM, postSlackChannel } from './services/slack.js'. Both are best-effort and never throw; failures land in service_errors (service slack, visible on /dashboard/admin/errors).

5. Future: auto-notifications

sendSlackDM / postSlackChannel are the primitives. To auto-DM a contributor when their PR merges, or post to a channel on a new contributor issue, wire a GitHub webhook (or a GitHub Action on PR-merge) to POST /api/slack/send or call the service directly — no new Slack plumbing needed.

SLACK INTEGRATION — Docs | HiveJournal