Skip to content

Slack Connector

Built-in connector for the Slack Web API using a bot token: post messages, manage channel membership, list channels, and look up users by email.

Developer workspace setup

  1. Create a workspace at slack.com (or use an existing dev workspace).
  2. Create an app at api.slack.com/apps → From scratch.
  3. Under OAuth & Permissions → Bot Token Scopes, add:
Scope Used by
chat:write postMessage
chat:write.public Post to public channels the bot has not joined (workspace policy permitting)
channels:read listChannels (public)
channels:manage inviteToChannel / removeFromChannel (public)
groups:read listChannels (private)
groups:write inviteToChannel / removeFromChannel (private)
users:read Resolve users when extending commands
users:read.email lookupUserByEmail (Slack gates email lookup behind this scope)
  1. Install App to Workspace and copy the Bot User OAuth Token (xoxb-…).
  2. In Floh, create a connector instance of type slack and paste the token into Bot token (encrypted at rest).
  3. Invite the bot to any channel where it should post or manage membership (/invite @YourBot).

Connection configuration

Create a connector instance via the Connectors API or UI with type slack.

Field Required Secret Description
botToken Yes Yes Bot User OAuth Token (xoxb-…)

Manual QA checklist

  • [ ] Test connection (test command) returns team and bot user.
  • [ ] postMessage to a channel ID (C…) the bot has joined.
  • [ ] inviteToChannel with a Slack user ID (U…).
  • [ ] removeFromChannel for the same user.
  • [ ] listChannels returns expected channel names.
  • [ ] lookupUserByEmail with a workspace email returns the matching userId (Slack U…).

Local HTTP mocks

Optional overlay:

docker compose -f docker/docker-compose.yml -f docker/docker-compose.slack-mock.yml up -d slackhog

SlackHog captures outbound Web API calls for inspection. Floh’s connectorHttpRequest URL policy may reject private-network targets (for example http://localhost:…) from the server container unless you use a publicly reachable mock URL. Prefer unit tests with mocked HTTP and a real dev workspace for integration QA.

Channel and user identifiers

  • Channels: use conversation IDs (C… / G…), not #name, unless your workspace resolves names elsewhere.
  • Users: inviteToChannel and removeFromChannel take Slack user IDs (U…). When a workflow only has an email address, run lookupUserByEmail first and feed its userId output into the membership command.
  • lookupUserByEmail: pass a plain address (you@company.com) or a single RFC-style Display Name <you@company.com> string; only the first line is used. The connector calls users.lookupByEmail via POST JSON body (not the legacy GET query-string form) so the email address never appears in network-layer URL logs (proxy access logs, NODE_DEBUG=http traces, etc.).
  • listChannels limit: Floh clamps the value to 1–1000 before calling Slack (conversations.list hard-caps at 1000).

Troubleshooting

Slack error / symptom Typical cause
restricted_action on removeFromChannel Workspace channel management policy: only certain roles may remove members, or the channel type (e.g. #general) is protected. Adjust policy under Settings → Administration → Workspace settings → Channel management, remove the user manually, or use a channel where the bot is allowed to manage membership.
not_in_channel on invite / post The bot has not been added to that channel (/invite @YourBot).
missing_scope Reinstall the app after adding bot scopes under OAuth & Permissions.
Area Path
Connector definition packages/server/src/modules/connectors/handlers/slack.ts
HTTP client & commands packages/server/src/modules/connectors/handlers/slack-support/
Unit tests packages/server/test/unit/connectors/slack-*.test.ts