Slack SDK for Python (Official)

3.27.0 · active · verified Thu Apr 16

The Slack SDK for Python provides a comprehensive and easy-to-use toolkit for building Slack applications. It offers corresponding packages for various Slack APIs, including Web API, Webhooks, Socket Mode, and OAuth. This library (and `slack_bolt`) is the official and actively maintained successor to `slackclient`. It is designed to be small, powerful, and to work seamlessly across different Slack platform features. The current version is 3.x, with frequent updates to support new Slack features and improvements.

Common errors

```
ModuleNotFoundError: No module named 'slackclient'
```
cause Attempting to import the old `slackclient` library after `slack_sdk` or `slack_bolt` has been installed, or `slackclient` was not installed at all.

fix Install `slack_sdk` (`pip install slack_sdk`) and update your imports from `slackclient` to `slack_sdk`. If you need to support older code, explicitly install `slackclient==2.x` (e.g., `pip install slackclient==2.9.3`) but migration to `slack_sdk` is strongly recommended.
```
slack_sdk.errors.SlackApiError: The request to the Slack API failed. (url: https://slack.com/api/chat.postMessage, status: 403, body: {'ok': False, 'error': 'invalid_auth'})
```
cause The Slack API token provided is invalid, expired, revoked, or lacks the necessary scopes for the requested operation.

fix Verify that your `SLACK_BOT_TOKEN` or `SLACK_USER_TOKEN` environment variable is correctly set and contains a valid token. Check your Slack App's 'OAuth & Permissions' page to ensure the token is still active and has the required OAuth scopes (e.g., `chat:write`, `channels:read`). Reinstalling the app to your workspace often resolves token issues.
```
slack_sdk.errors.SlackApiError: The request to the Slack API failed. (url: https://slack.com/api/chat.postMessage, status: 200, body: {'ok': False, 'error': 'channel_not_found'})
```
cause The specified channel ID or name does not exist, or the bot user is not a member of the channel.

fix Ensure the channel ID or name is correct. If using a bot token, invite the bot user to the target channel (e.g., by mentioning it in the channel `/@your_bot_name`). For public channels, consider adding `chat:write.public` scope to your bot token.
```
UserWarning: slack package is deprecated. Please use slack_sdk.web/webhook/rtm package instead.
```
cause You are importing modules from the transitional `slack` package, which is a deprecated alias provided for backward compatibility after the rename from `slackclient` to `slack_sdk`.

fix Update your import statements to use `slack_sdk` directly. For example, change `from slack.web import WebClient` to `from slack_sdk.web import WebClient` or simply `from slack_sdk import WebClient` if directly importing the top-level class.

Warnings

breaking The original `slackclient` library is in maintenance mode, and `slack_sdk` is its official successor. Direct migration from `slackclient` v1.x to v2.x (and then to `slack_sdk` v3.x) involved significant breaking changes in import paths and API usage.
Fix: Migrate your application to `slack_sdk`. Review the official migration guides for `slackclient` v1.x to v2.x and v2.x to `slack_sdk` v3.x. Key changes include importing `slack_sdk` instead of `slackclient`, and explicit dependency on `aiohttp` for async clients.
gotcha There is an unrelated, minimally maintained Python package also named `slack` (version 0.0.3) on PyPI, which is described as 'a DI container'. This is *not* the official Slack library for interacting with the Slack platform. Installing `pip install slack` will install the DI container, not the Slack API client.
Fix: Always install `slack_sdk` (for the core SDK) or `slack_bolt` (for the framework) when intending to interact with the Slack API. E.g., `pip install slack_sdk`. Do not install `pip install slack` for Slack API interaction.
deprecated The `files.upload` Web API method has been deprecated as of May 16, 2024, for newly created Slack apps. It will be fully retired on November 12, 2025.
Fix: Migrate to the new asynchronous upload flow for files. Refer to the Slack Developer documentation for details on `files_upload_v2` and the recommended asynchronous approach.
breaking Support for legacy custom bots and classic apps will be discontinued. Legacy custom bots will cease to function after March 31, 2025. Support for classic apps will be discontinued in November 2026 (though this date has been subject to change).
Fix: Migrate existing legacy custom bots and classic apps to new Slack apps built with modern Slack Platform features and libraries like `slack_sdk` or `slack_bolt`.
gotcha Incorrect token usage (e.g., using a bot token `xoxb-` where a user token `xoxp-` is expected, or vice-versa) is a common source of 'invalid_auth' or 'BotUserAccessError'.
Fix: Ensure the correct token type is used for the specific API method being called and that the token has the necessary scopes. User tokens start with `xoxp-`, bot tokens with `xoxb-`, and app-level tokens (for Socket Mode) with `xapp-`.

Install

pip install slack_sdk Basic Installation
pip install slack_bolt For building Slack apps with Bolt framework
pip install slack_sdk aiohttp For asynchronous WebClient usage

Imports

WebClient
wrong:
```
from slackclient import SlackClient
```
correct:
```
from slack_sdk import WebClient
```
slackclient is in maintenance mode; slack_sdk is the successor.
App
wrong:
```
from slack_sdk import App
```
correct:
```
from slack_bolt import App
```
The 'App' class for building Slack applications with event listeners is part of the `slack_bolt` framework, not directly `slack_sdk`.
SlackApiError
```
from slack_sdk.errors import SlackApiError
```
For handling API-specific errors.

Quickstart

This quickstart demonstrates sending a basic message to a Slack channel using the `WebClient` from `slack_sdk`. It handles authentication via an environment variable and includes basic error handling for common API issues. A commented-out example for a simple 'hello' response using the `slack_bolt` framework is also provided. Remember to set `SLACK_BOT_TOKEN` (and `SLACK_APP_TOKEN` for Socket Mode) environment variables.

import os
from slack_sdk import WebClient
from slack_sdk.errors import SlackApiError

# Your bot token (xoxb-...) or user token (xoxp-...)
# You can find these at https://api.slack.com/apps
slack_token = os.environ.get('SLACK_BOT_TOKEN', 'YOUR_SLACK_BOT_TOKEN')

client = WebClient(token=slack_token)

try:
    response = client.chat_postMessage(
        channel='#general', # Or a channel ID like 'C12345ABC'
        text='Hello from your Python Slack SDK app!'
    )
    print(f"Message posted: {response['ts']}")
except SlackApiError as e:
    # You will get a SlackApiError if 'ok' is False
    print(f"Error sending message: {e.response['error']}")
    # e.g., 'invalid_auth', 'channel_not_found', 'not_in_channel' etc.
    if e.response['error'] == 'invalid_auth':
        print("Please check your SLACK_BOT_TOKEN or SLACK_APP_TOKEN environment variable.")
    elif e.response['error'] == 'channel_not_found':
        print("The specified channel does not exist or your bot is not in it.")

# Example for Slack Bolt App (requires 'pip install slack_bolt')
# from slack_bolt import App
# from slack_bolt.adapter.socket_mode import SocketModeHandler

# app = App(token=os.environ.get('SLACK_BOT_TOKEN'))

# @app.message("hello")
# def message_hello(message, say):
#     say(f"Hey there <@{message['user']}>!")

# if __name__ == "__main__":
#     SocketModeHandler(app, os.environ.get("SLACK_APP_TOKEN")).start()

view raw JSON →