setting-up-support-slack-locally

Setting up Support Slack locally

Slack is SaaS-only, so "local" means a throwaway Slack workspace + app whose OAuth and events reach your laptop. The job has one non-obvious idea that avoids almost every wall: the OAuth connect and the event webhook have opposite reachability needs, so you point them at different places.

• OAuth connect is browser-mediated. Your browser follows the redirect, so localhost is reachable. No tunnel needed.
• Inbound events (Slack POSTing messages so they become tickets) are server-to-server from Slack's cloud. Slack cannot reach localhost, so this one needs a public tunnel.

Keep the whole app and the OAuth flow on localhost, and point only Event Subscriptions (and Interactivity) at the tunnel. This also sidesteps free-tier tunnel rate limits, since the tunnel then carries only Slack's low-volume event POSTs rather than the entire SPA.

This is the conversations/SupportHog variant of the general Slack local setup guide; that guide covers the PostHog Desktop / notifications Slack app (SLACK_APP_*, /integrations/slack/callback). Conversations uses its own SUPPORT_SLACK_* credentials and /api/conversations/v1/slack/* routes, but the tunnel and SITE_URL mechanics are identical.

The endpoints

All under products/conversations/backend/api/urls.py, prefixed /api/conversations/:

The callback requires an authenticated session on whatever origin SITE_URL resolves to, because the session cookie is per-origin. Keep SITE_URL on localhost and log in there, and the callback keeps your session.

Step 1 — credentials

SUPPORT_SLACK_APP_CLIENT_ID, SUPPORT_SLACK_APP_CLIENT_SECRET, and SUPPORT_SLACK_SIGNING_SECRET are django-constance dynamic settings (posthog/settings/dynamic_settings.py) that default to the matching env var. Empty client id is what produces "Support Slack OAuth client ID is not configured". Put your Slack app's values in .env.local (gitignored) and restart the backend:

SUPPORT_SLACK_APP_CLIENT_ID=<client id>
SUPPORT_SLACK_APP_CLIENT_SECRET=<client secret>
SUPPORT_SLACK_SIGNING_SECRET=<signing secret>

Constance stores values in the DB, and a stored value overrides the env default. If it still reads as unconfigured after a restart, check /admin/constance/config/ for a blank stored value and set it there instead.

Step 2 — the Slack app

At api.slack.com/apps, create an app in a throwaway workspace, then:

1. App Home → enable a bot user (give it a display name). Without this, install fails with "requesting permission to install a bot ... but it's not currently configured with a bot".
2. OAuth & Permissions → Bot Token Scopes — the flow requests these (from SUPPORTHOG_SLACK_SCOPES in products/conversations/backend/api/slack_oauth.py): channels:history, channels:read, chat:write, chat:write.customize, files:read, files:write, groups:history, groups:read, reactions:read, users:read, users:read.email. Attachments need the two files: scopes in both directions, so a workspace installed without them shows a "reconnect" banner in support settings.
3. OAuth & Permissions → Redirect URLs — add http://localhost:8010/api/conversations/v1/slack/callback and Save. If Slack refuses a plain-http localhost URL, use the tunnel URL for the callback too and log in once on the tunnel origin (see references/troubleshooting.md).
4. Copy the Client ID, Client Secret, and Signing Secret from Basic Information into .env.local (Step 1).

Step 3 — tunnel for inbound events

Run any HTTPS tunnel pointed at Caddy on 8010, rewriting the upstream Host header to localhost (the dev Caddy only answers for the localhost host; without the rewrite you get an empty 200 and a white page):

ngrok http --host-header=localhost 8010
# or, free with no rate limit:
cloudflared tunnel --url http://localhost:8010 --http-host-header localhost

Verify it reaches Django, not just Caddy:

curl -sS https://<tunnel-host>/_preflight | head -c 120   # want JSON, server: granian

Then in the Slack app set Event Subscriptions → Request URL (and Interactivity → Request URL if testing buttons) to https://<tunnel-host>/api/conversations/v1/slack/events (and .../interactivity). Slack sends a synchronous url_verification challenge on save, so the backend must be up; the handler echoes it back automatically.

The Request URL alone only passes verification; it delivers nothing until you subscribe to events. Under Event Subscriptions → Subscribe to bot events, add the events the backend handles (SUPPORT_EVENT_TYPES in products/conversations/backend/api/slack_events.py):

• app_mention
• message.channels (and message.groups for private channels), both arriving as the inner message event
• reaction_added
• member_joined_channel, member_left_channel

Reinstall the app after changing scopes/events so the new grants take effect.

Step 4 — connect and test

Browse the app at http://localhost:8010, log in, go to Support settings, and connect Slack. The OAuth round-trip completes on localhost. Then invite the bot to a channel in your dev workspace and post a message; it should arrive as a ticket, and a reply from the ticket should post back to the thread.

For the failure modes worth recognizing (white screen, "Network error", redirect mismatch, region routing), see references/troubleshooting.md.