SuperAPI AI Directory
Partner中文AI newsFavorites
Skillssetting-up-support-slack-locally

setting-up-support-slack-locally

Office & productivity

View repository

Updated 10-16 03:45

About this skill

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/:

Route Purpose Reachability
v1/slack/authorize returns the Slack OAuth URL (auth-gated) browser (localhost)
v1/slack/callback OAuth redirect target; built from SITE_URL, no forced https browser (localhost)
v1/slack/events inbound event webhook, built on posthog/ingress/ Slack's servers (tunnel)
v1/slack/interactivity interactive component callbacks Slack's servers (tunnel)

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 (SLACK_EVENT_TYPES in posthog/ingress/slack/provider.py, which is also what the consumer registers for):

  • 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.

Region routing, locally

The events endpoint is an ingress view: products/conversations/backend/api/slack_events.py wires the Slack provider into build_webhook_view(), and ingress verifies the signature, parses the envelope and hands each delivery to the conversations_slack consumer.

Which region handles a delivery is two separate answers:

  1. The consumer's ownership lookup, slack_delivery_ownership in products/conversations/backend/services/slack_events.py. A workspace this database is connected to is LOCAL; a workspace it does not know is ELSEWHERE.
  2. The ingress forward, which replays the signed request to SECONDARY_REGION_DOMAIN when any consumer answered ELSEWHERE and the request arrived on the primary region. See Regional forwarding.

posthog/regions.py holds both domains, and under DEBUG it rewrites them: the primary becomes urlparse(SITE_URL).netloc (localhost:8010 with the default dev SITE_URL) and the secondary becomes localhost:8000.

The old handler also had a DEBUG-only shortcut that forwarded from the primary region even when the local database held the workspace. That is gone. Ownership answers from the data alone in every environment, so a workspace your local stack is connected to is always handled locally.

To exercise the forward on your laptop you need all three of: a request whose Host is the primary domain, a team_id no local team is connected to, and something listening on localhost:8000. The tunnel cannot give you the first, because the host rewrite makes the request arrive as bare localhost, which is not localhost:8010. So sign a body yourself and POST it straight at http://localhost:8010/... (the snippet in references/troubleshooting.md signs one for you) with an unknown team_id. Without a second stack on localhost:8000 the forward fails and the endpoint answers 502, which is still proof that the forward was attempted; with one, the delivery lands there.

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.