Slack integration

Mentions ships a Slack bot that posts new relevant mentions to a channel you pick. Connecting is a standard OAuth install: no tokens to copy, and disconnecting revokes the bot's access.

Connecting from the dashboard

The short path is Settings, then Slack notifications:

1. Connect Slack: you are sent to Slack's consent screen and back.
2. Pick a channel and a relevance threshold (all relevant mentions, or only 50+, 70+, 85+).
3. Turn on notifications.

The bot can post to any public channel without being invited. For private channels, invite @Mentions to the channel first; the picker only lists public ones.

What lands in the channel

Each matching mention arrives as a compact message:

New mention of "your product" on hackernews
Positive firsthand report of building on the product.
https://news.ycombinator.com/item?id=...

Delivery follows the pipeline rules:

• Only classified mentions that pass your threshold are sent; filtered noise never reaches Slack.
• Mentions you triage as ignored or done before delivery are skipped.
• Transient failures (rate limits, Slack hiccups) retry up to 5 times; a revoked token or deleted channel fails permanently and is surfaced in delivery history instead of retrying forever.

Connecting via the API

Everything the dashboard does is plain REST:

# 1. Start the install; send the user to the returned URL.
curl -X POST "$MENTIONS_API_URL/v1/slack/install" \
  -H "Authorization: Bearer $MENTIONS_API_KEY"
# { "url": "https://slack.com/oauth/v2/authorize?..." }

# 2. After the user authorizes, check the connection.
curl -H "Authorization: Bearer $MENTIONS_API_KEY" "$MENTIONS_API_URL/v1/slack/status"
# { "configured": true, "connected": true, "teamName": "Acme", "notifications": null }

# 3. List channels and point notifications at one.
curl -H "Authorization: Bearer $MENTIONS_API_KEY" "$MENTIONS_API_URL/v1/slack/channels"
curl -X PUT "$MENTIONS_API_URL/v1/slack/notifications" \
  -H "Authorization: Bearer $MENTIONS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channelId": "C0123ABC", "channelName": "brand-mentions", "minRelevance": 70 }'

DELETE /v1/slack/notifications turns notifications off but keeps the workspace connected; DELETE /v1/slack disconnects entirely and revokes the bot token. See the Slack reference for full schemas.

Errors

Self-hosting: configuring the Slack app

The integration switches on when the API worker has Slack app credentials; without them, Slack endpoints return 503 slack_not_configured and everything else keeps working.

1. Create an app at api.slack.com/apps with "From a manifest" and paste workers/api/slack-app-manifest.json (it declares the bot scopes chat:write, chat:write.public, channels:read and the OAuth redirect URL; adjust the redirect to https://<your-api-host>/v1/slack/callback for your deployment).
2. Activate public distribution (Manage Distribution) so workspaces other than your own can install the app.
3. Set the credentials from Basic Information on the API worker:

wrangler secret put SLACK_CLIENT_ID
wrangler secret put SLACK_CLIENT_SECRET