@chat-adapter/slack weekly downloads statistics

@chat-adapter/slack

npm package: @chat-adapter/slack

Slack adapter for Chat SDK. Configure single-workspace or multi-workspace OAuth deployments.

Documentation: chat-sdk.dev/adapters/official/slack · Guides: vercel.com/kb/chat-sdk

Installation

Scaffold with the CLI

To scaffold a new Slack bot with this adapter preselected:

Visit the adapters directory to see other available official and vendor-official adapters.

Quick start

For managed credentials and webhook verification, see Vercel Connect.

For bots deployed to a single Slack workspace. The adapter auto-detects SLACK_BOT_TOKEN and SLACK_SIGNING_SECRET from environment variables:

Configuration

All options are auto-detected from environment variables when not provided. You can call createSlackAdapter() with no arguments if the env vars are set.

| Option | Required | Description |

| botToken | No | Bot token (xoxb-...) or a function returning one (sync or async) for rotation/lazy fetch. Auto-detected from SLACK_BOT_TOKEN | | signingSecret | No* | Signing secret for webhook verification. Auto-detected from SLACK_SIGNING_SECRET | | webhookVerifier | No* | Custom verifier (request, body) => unknown \| Promise used in place of signingSecret. Returning a string substitutes the verified body for downstream parsing | | mode | No | Connection mode: "webhook" (default) or "socket" | | appToken | No** | App-level token (xapp-...) for socket mode. Auto-detected from SLACK_APP_TOKEN | | socketForwardingSecret | No | Shared secret for authenticating forwarded socket events. Auto-detected from SLACK_SOCKET_FORWARDING_SECRET, falls back to appToken | | clientId | No | App client ID for multi-workspace OAuth. Auto-detected from SLACK_CLIENT_ID | | clientSecret | No | App client secret for multi-workspace OAuth. Auto-detected from SLACK_CLIENT_SECRET | | encryptionKey | No | AES-256-GCM key for encrypting stored tokens. Auto-detected from SLACK_ENCRYPTION_KEY | | installationKeyPrefix | No | Prefix for the state key used to store workspace installations. Defaults to slack:installation. The full key is {prefix}:{teamId} (or {prefix}:{enterpriseId} for Enterprise Grid org-wide installs) | | installationProvider | No | External installation lookup { getInstallation(installationId, isEnterpriseInstall) => Promise }. When set, bypasses the internal state adapter for token resolution on incoming webhooks. Read-only — manage your own writes externally | | apiUrl | No | Override the Slack Web API base URL (e.g. for GovSlack or a self-hosted gateway). Auto-detected from SLACK_API_URL | | fetch | No | Fetch for response URLs and Socket Mode webhook forwarding; defaults to global fetch | | fileTransport | No | Guarded file download transport; custom transports own connection/DNS policy | | webClientOptions | No | Options forwarded to Slack WebClient instances, excluding slackApiUrl. Supports retryConfig, per-request timeout, and rejectRateLimitedCalls; agent also configures Socket Mode, tls only its HTTP calls | | logger | No | Logger instance (defaults to ConsoleLogger("info")) |

*signingSecret is required for webhook mode — either via config, SLACK_SIGNING_SECRET env var, or a webhookVerifier. **appToken is required for socket mode — either via config or SLACK_APP_TOKEN env var.

Authentication

Vercel Connect

Use Vercel Connect to source the bot token at runtime instead of storing one. The connectSlackAdapter() helper from @vercel/connect/chat wires both a botToken resolver and a webhookVerifier for Connect trigger-forwarded webhooks:

This is equivalent to passing a botToken resolver that calls getToken and a webhookVerifier that validates the Vercel OIDC token Connect attaches. Omit signingSecret / SLACK_SIGNING_SECRET when using it.

Single-workspace mode

Provide SLACK_BOT_TOKEN and SLACK_SIGNING_SECRET as shown in Quick start.

Token rotation

botToken accepts a function returning a string or Promise — the resolver is invoked per API call, so it composes with Slack token rotation (12-hour TTL) or lazy fetch from a secret manager:

If the resolver is expensive (e.g. a vault round-trip), implement caching inside the resolver itself.

Custom webhook verification

Pass webhookVerifier to replace the built-in HMAC check — useful when verification runs in a proxy or signing layer ahead of your handler:

If both signingSecret and webhookVerifier are set, webhookVerifier wins — it also takes precedence over the SLACK_SIGNING_SECRET env var, so an env-configured deployment can't silently shadow a verifier you wired up. When using webhookVerifier, you are responsible for replay/timestamp protection — the built-in 5-minute timestamp tolerance only applies to the signingSecret path.

Multi-workspace mode

For apps installed across multiple Slack workspaces via OAuth, omit botToken and provide OAuth credentials instead. The adapter resolves tokens dynamically from your state adapter using the team_id from incoming webhooks — or enterprise_id for Enterprise Grid org-wide installs (is_enterprise_install: true).

When you pass any auth-related config (like clientId), the adapter won't fall back to env vars for other auth fields, preventing accidental mixing of auth modes.

OAuth callback

The adapter handles the full Slack OAuth V2 exchange. Point your OAuth redirect URL to a route that calls handleOAuthCallback:

If your install flow uses a specific redirect URI, pass the same value here that you used during the authorize step. This is especially useful when one app supports multiple redirect URLs. When no option is provided, the adapter still falls back to redirect_uri on the callback request URL.…

Description from the npm listing.