Slack Web API Client

Common errors

• SlackAPIError: The request to the Slack API failed. (response: { ok: false, error: 'invalid_auth' })

  cause The Slack API token provided to the client is missing, invalid, or has insufficient scopes.
  fix Verify that your `SLACK_BOT_TOKEN` environment variable (or hardcoded token) is correctly set and starts with `xoxb-` or `xoxp-`. Ensure your Slack app has the necessary OAuth scopes for the API method being called (e.g., `chat:write` for `chat.postMessage`).

• TypeError: client.chat is not a function

  cause This error typically indicates that the `SlackAPIClient` instance was not properly initialized or the method chain is incorrect.
  fix Double-check that `new SlackAPIClient(token)` was called with a valid token. Confirm that the API method path (e.g., `chat.postMessage`) matches the Slack Web API documentation and the client's exposed methods.

Warnings

• gotcha By default, the `SlackAPIClient` is configured to throw a `SlackAPIError` when a Slack API call returns `ok: false` in its response. Developers accustomed to checking the `ok` property directly or receiving a structured error object without an exception might find this behavior unexpected.
  Fix: To handle API failures without exceptions, set `throwSlackAPIError: false` in the client's constructor options: `new SlackAPIClient(token, { throwSlackAPIError: false })`. Alternatively, wrap your API calls in `try...catch` blocks to catch `SlackAPIError` instances.
• gotcha The client requires a valid Slack Bot Token (e.g., `xoxb-YOUR_TOKEN`) or User Token (e.g., `xoxp-YOUR_TOKEN`) for authentication. Using an invalid, expired, or improperly scoped token will result in API errors.
  Fix: Ensure the `process.env.SLACK_BOT_TOKEN` (or equivalent) environment variable is correctly set with a valid token and that the associated bot or user has the necessary OAuth scopes for the API methods you are calling.
• gotcha While the library is fetch-based and designed for various runtimes, specific runtime environments (like Cloudflare Workers or Deno) may require slightly different setup or polyfills for `process.env` access, depending on how environment variables are exposed.
  Fix: Consult the specific runtime's documentation for handling environment variables. For Deno, refer to the Deno-specific README provided by the library. For Cloudflare Workers, use Worker-native ways to access secrets (e.g., `env.SLACK_BOT_TOKEN`).

Install

• npm install slack-web-api-client npm
• yarn add slack-web-api-client yarn
• pnpm add slack-web-api-client pnpm

Imports

• SlackAPIClient
  wrong:

  const SlackAPIClient = require('slack-web-api-client').SlackAPIClient;

  correct:

  import { SlackAPIClient } from 'slack-web-api-client';

  Primary class for interacting with the Slack Web API. Use ESM import for modern TypeScript/JavaScript projects.
• SlackAPIError
  wrong:

  import SlackAPIError from 'slack-web-api-client/errors';

  correct:

  import { SlackAPIError } from 'slack-web-api-client';

  Import this class for handling specific errors thrown by the client. The client throws this error by default on API failures (when `ok: false`).
• WebClientOptions
  wrong:

  import { Options } from 'slack-web-api-client';

  correct:

  import { WebClientOptions } from 'slack-web-api-client';

  Type definition for the optional configuration object passed to the SlackAPIClient constructor.

Quickstart

This quickstart demonstrates how to instantiate the SlackAPIClient, configure it, and use it to post a message with Block Kit to a specified Slack channel, including basic error handling.

import { SlackAPIClient } from "slack-web-api-client";

// Ensure SLACK_BOT_TOKEN is set in your environment
const token = process.env.SLACK_BOT_TOKEN ?? '';

const client = new SlackAPIClient(token, {
  // Log level can be set to 'DEBUG', 'INFO' (default), 'WARN', 'ERROR'
  logLevel: "INFO", 
  // By default, the client throws SlackAPIError for API failures (ok: false)
  throwSlackAPIError: true
});

async function postGreeting() {
  if (!token) {
    console.error('SLACK_BOT_TOKEN environment variable is not set.');
    return;
  }
  try {
    const response = await client.chat.postMessage({
      channel: "#general", // Replace with your desired channel ID or name
      text: ":wave: Hello from slack-web-api-client!",
      blocks: [
        {
          "type": "section",
          "text": {
            "type": "mrkdwn",
            "text": "Hey there! I just posted this message using the `slack-web-api-client` library. :rocket:"
          }
        },
        {
          "type": "actions",
          "elements": [
            {
              "type": "button",
              "text": {
                "type": "plain_text",
                "text": "View GitHub"
              },
              "url": "https://github.com/slack-edge/slack-web-api-client"
            }
          ]
        }
      ]
    });
    console.log('Message posted:', response.ts);
  } catch (error) {
    if (error instanceof SlackAPIClient) {
      console.error('Slack API Error:', error.code, error.response);
    } else {
      console.error('An unexpected error occurred:', error);
    }
  }
}

postGreeting();