@slack/web-api

@slack/web-api is the official Node.js client for Slack’s Web API, maintained by Slack Technologies as part of the node-slack-sdk monorepo. It exports a WebClient class with a named, typed method for every public Web API endpoint (chat.postMessage, conversations.list, users.info, and hundreds more), so calls read as web.chat.postMessage({...}) instead of hand-built HTTP requests against Slack’s method catalog.

Beyond simple request/response wrapping, the client handles the operational concerns that come with talking to a rate-limited third-party API at scale: an internal request queue caps concurrency, failed calls are retried with configurable backoff policies, HTTP 429 responses pause the queue and resume automatically once Slack’s retry-after window elapses, and cursor-paginated list methods can be consumed as an async iterator via web.paginate() instead of manually tracking response_metadata.next_cursor. A dedicated filesUploadV2 helper and ChatStreamer class wrap Slack’s newer multi-step file-upload and streaming-message flows behind a single call.

Because the whole SDK is generated from Slack’s API definitions, the request and response argument types stay in lockstep with the platform, giving TypeScript users inline hints for every method’s parameters without leaving their editor. Errors are modeled as a small class hierarchy (WebAPIPlatformError, WebAPIRequestError, WebAPIHTTPError, WebAPIRateLimitedError) rooted in a shared SlackError, so callers can instanceof-check the failure mode instead of parsing string codes.

@slack/web-api is typically installed alongside sibling packages from the same monorepo — @slack/oauth for install flows, @slack/socket-mode or @slack/webhook for receiving events — but it has no dependency on them and works standalone for any app that only needs to call the Web API.

What You Get

• A WebClient class with a method for each of Slack’s 270+ Web API endpoints, callable as web.chat.postMessage(...), web.conversations.list(...), etc., or dynamically via web.apiCall(methodName, options).
• Automatic request retries with pluggable retryConfig policies (default ~10 retries over 30 minutes), plus automatic pause-and-resume handling for HTTP 429 rate-limit responses.
• Cursor pagination built in via web.paginate(method, options), usable as an async iterator (for await...of) or with a stop/reduce callback pair for functional-style accumulation.
• A typed error hierarchy (WebAPIPlatformError, WebAPIHTTPError, WebAPIRequestError, WebAPIRateLimitedError, all extending SlackError) so failure handling can branch on instanceof instead of string matching.
• A filesUploadV2 helper and ChatStreamer class that wrap Slack’s multi-request file-upload and streaming-message-append flows behind single method calls.
• Full TypeScript types for every method’s request arguments and response shape, generated to track Slack’s platform API definitions.

Common Use Cases

• Slack bots and apps - posting and updating messages, reacting, and managing channels from a bot token without hand-rolling HTTP calls to Slack.
• Backend integrations - syncing users, channels, or files between Slack and an internal system using the typed method surface and built-in pagination for *.list endpoints.
• Admin and Enterprise Grid tooling - calling admin.* methods (user provisioning, conversation management, analytics exports) with the same retry/rate-limit handling as any other method.
• Custom Slack workflow steps and interactivity - responding to Slack events (typically received via Bolt or a raw event listener) by calling back into the Web API to post results or update UI.
• Streaming/long-running responses - using chatStream() to append incrementally generated (e.g. LLM-produced) text into a Slack message without re-posting the whole message on every update.

Under The Hood

Architecture The package is organized around a single WebClient class (WebClient.ts) that extends a generated Methods class (methods.ts, ~2,600 lines) providing one property-per-namespace, method-per-endpoint surface (e.g. client.chat.postMessage) that all funnel into WebClient.apiCall(). apiCall builds the request URL, serializes the body (serializeBody, choosing multipart/form-data when binary content is present, otherwise URL-encoding), routes it through a p-queue-backed makeRequest that enforces maxRequestConcurrency and wraps the actual fetch call in p-retry, and finally normalizes the response in buildResult (including a special path for gzip-encoded analytics-export responses). Pagination (paginate()), file uploads (filesUploadV2, delegating to file-upload.ts), and streaming messages (chatStream(), delegating to chat-stream.ts) are each implemented as focused helpers layered on top of the same apiCall/makeRequest core, so the request pipeline has one entry point regardless of which higher-level feature is used. Runtime warnings (deprecated methods, missing text/fallback on message-posting calls, non-string thread_ts) are attached directly inside apiCall rather than as separate middleware.

Tech Stack Written in TypeScript and built with tsc against Node >=20, using the platform’s native fetch/FormData/AbortSignal rather than a bundled HTTP library, with a caller-injectable fetch option for proxies or custom transports. Concurrency and retry behavior come from small, focused dependencies: p-queue for the request queue, p-retry (built on retry) for exponential backoff, and eventemitter3 for the rate_limited event. @slack/types and @slack/logger are sibling packages from the same monorepo, pulled in as regular dependencies rather than duplicated. The repo itself is an npm workspaces monorepo (packages/web-api alongside oauth, socket-mode, webhook, etc.) built via a shared scripts/build.sh, linted and formatted with Biome, and documented through TypeDoc with a markdown output plugin.

Code Quality Tests use Node’s built-in node:test runner (via tsx) rather than a third-party framework, with nock for HTTP mocking and sinon for spies/stubs; WebClient.test.ts, file-upload.test.ts, and instrument.test.ts cover the client’s core request path, file-upload flow, and user-agent instrumentation respectively, and a separate tsd-based suite (test:types) exercises the exported TypeScript types directly. Error handling is explicit and typed throughout — a SlackError base class with per-failure-mode subclasses rather than generic thrown strings or swallowed exceptions — and the codebase is TypeScript-strict with Biome enforcing lint rules and import organization. GitHub Actions run a CI build workflow (ci-build.yml) plus dependency and release-automation workflows on every push, so the test/lint/build path is continuously enforced rather than run only locally.

API Design The defining ergonomic choice is generating one strongly-typed method per Slack Web API endpoint instead of exposing a single generic request(method, params) call — callers get autocomplete and inline argument documentation for all 270+ methods straight from their editor, while apiCall() remains available underneath for dynamic method names or brand-new endpoints not yet in the generated surface. Getting started requires only new WebClient(token) and a single awaited call; pagination, retries, and rate-limiting are on by default and only need configuration when the defaults don’t fit, which keeps the common path free of boilerplate while still exposing escape hatches (retryConfig, maxRequestConcurrency, custom fetch) for advanced use.