Slack

Connect a Slack app (bot user) so people in your workspace can talk to a governed flow by DM or by @mentioning the bot in a channel. Replies land in the DM or as a thread reply under the mention.

What you need

• A Slack workspace where you can create/install apps (workspace admin or app install permission).
• A public HTTPS URL for this gateway (the console shows the exact webhook URL once you connect).

Official documentation

• Events API: https://docs.slack.dev/apis/events-api
• Verifying requests from Slack (signing secret): https://docs.slack.dev/authentication/verifying-requests-from-slack
• chat.postMessage: https://docs.slack.dev/reference/methods/chat.postMessage
• auth.test: https://docs.slack.dev/reference/methods/auth.test
• Creating apps: https://api.slack.com/apps

Set up on Slack

1. Go to https://api.slack.com/apps → Create New App → From scratch, name it and pick the workspace.
2. OAuth & Permissions → Bot Token Scopes: add chat:write, im:history, app_mentions:read, channels:history (add groups:history for private channels, mpim:history for group DMs).
3. App Home → enable Messages Tab and Allow users to send Slash commands and messages from the messages tab (so people can DM the bot).
4. Install App → Install to Workspace → copy the Bot User OAuth Token (xoxb-…).
5. Basic Information → App Credentials → copy the Signing Secret.
6. Connect in Tools Anatomy (below) to obtain the Request URL, then Event Subscriptions → Enable Events → paste the URL. Slack sends a url_verification challenge; the connector answers it automatically and Slack shows Verified.
7. Same page → Subscribe to bot events: message.im, app_mention (optionally message.channels / message.groups to answer every message in channels the bot is in). Save Changes and reinstall the app if Slack asks.
8. Invite the bot to the channels where it should answer (/invite @YourBot).

Connect in Tools Anatomy

/channels → Messaging channels → Slack → paste:

Field	Where it comes from
Bot User OAuth Token	OAuth & Permissions → Bot User OAuth Token (xoxb-…)
Signing Secret	Basic Information → App Credentials

The console then shows the Event Subscriptions Request URL (…/v1/public/channels/slack/<hook>/events) to paste in step 6. Both values are stored in the Secret Manager; the console never shows them again.

Identity we derive

Canonical key	Value
external_user_id	<team_id>:<user_id> (Slack identity is the workspace+user pair)
channel	slack
display_name, email, phone_number	not provided (would need users:read / users:read.email; see channel-identity-reference.md)

conversation_context.channel_account_id = the workspace (team_id). Threads: a DM is one conversation per DM channel; in channels each mention thread is its own conversation and the bot replies in-thread.

Limits

• Slack requires a 2xx within 3 seconds; the gateway acknowledges immediately and replies asynchronously. Slack retries up to 3 times (x-slack-retry-num); retries are deduped on event_id.
• Replies longer than ~4000 characters are split into several messages.
• chat.postMessage is rate limited (roughly 1 message/second/channel).
• Signature timestamps older than 5 minutes are rejected (replay protection).

Test it

DM the bot from Slack, or post @YourBot hello in a channel it was invited to. The transcript appears under the channel's Conversations in the console.

Troubleshooting

• Request URL not verified: connect the channel first (the signing secret must be stored before Slack's challenge arrives); check the public URL.
• Bot answers nothing in a channel: the bot must be invited and app_mention subscribed; without message.channels it only reacts to mentions.
• invalid_auth / not_authed: the bot token was revoked or the app was reinstalled with a new token — reconnect with the new xoxb- token.