slack-api-python

name: slack-api-python description: "Guide for building Slack apps and integrations with Python. Use this skill whenever the user wants to build a Slack bot, send messages to Slack, listen to Slack events, handle slash commands, create interactive modals, use Block Kit, implement OAuth for Slack, build AI agents/assistants for Slack, create custom workflow steps, or integrate with the Slack platform. Also trigger when code imports slack_bolt, slack_sdk, or slack_sdk.web, or when the user mentions 'Slack API', 'Slack bot', 'Slack app', 'Bolt for Python', or 'slack_sdk' in a development context."

Slack API Python Development Guide

Build Slack apps and integrations using Python. Two main libraries: Bolt for Python (slack_bolt) as the high-level app framework, and Python Slack SDK (slack_sdk) as the low-level API client.

Quick Reference

Reference Files

Read these for detailed examples when implementing specific features:

When to Use What

Installation

# Bolt framework (includes slack_sdk as dependency)
pip install slack_bolt

# SDK only (if you don't need the framework)
pip install slack_sdk

Setup & Authentication

Token Types

Never hardcode tokens. Use environment variables:

import os
SLACK_BOT_TOKEN = os.environ["SLACK_BOT_TOKEN"]
SLACK_APP_TOKEN = os.environ["SLACK_APP_TOKEN"]  # for Socket Mode

Bolt App — Quick Start (Socket Mode)

import os
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']}>!")

@app.command("/echo")
def handle_echo(ack, respond, command):
    ack()
    respond(f"{command['text']}")

@app.event("app_mention")
def handle_mention(event, say):
    say(f"Hi <@{event['user']}>! You mentioned me.")

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

Bolt App — HTTP Mode

import os
from slack_bolt import App

app = App(
    token=os.environ.get("SLACK_BOT_TOKEN"),
    signing_secret=os.environ.get("SLACK_SIGNING_SECRET"),
)

# ... add handlers ...

if __name__ == "__main__":
    app.start(port=int(os.environ.get("PORT", 3000)))

SDK — Direct API Calls

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

client = WebClient(token=os.environ["SLACK_BOT_TOKEN"])

# Send a message
try:
    result = client.chat_postMessage(channel="#general", text="Hello from Python!")
    print(f"Message sent: {result['ts']}")
except SlackApiError as e:
    print(f"Error: {e.response['error']}")

# List channels
result = client.conversations_list()
for channel in result["channels"]:
    print(channel["name"])

# Upload a file
result = client.files_upload_v2(
    channels=["C12345"],
    file="./report.csv",
    title="Daily Report",
    initial_comment="Here's today's report",
)

Webhook — Send Messages Without a Bot

from slack_sdk.webhook import WebhookClient

webhook = WebhookClient(url=os.environ["SLACK_WEBHOOK_URL"])
response = webhook.send(text="Hello from a webhook!")

Core Bolt Concepts

Listener Decorator Reference

Common Listener Arguments

Acknowledgement Rule

Actions, commands, shortcuts, options, and view submissions must always be acknowledged with ack() within 3 seconds. Call ack() immediately before any time-consuming work.

Block Kit — Building Rich UIs

Block Kit provides reusable, stackable, interactive components for messages, modals, and App Home.

Message with Button

@app.message("hello")
def message_hello(message, say):
    say(
        blocks=[
            {
                "type": "section",
                "text": {"type": "mrkdwn", "text": f"Hey <@{message['user']}>!"},
                "accessory": {
                    "type": "button",
                    "text": {"type": "plain_text", "text": "Click Me"},
                    "action_id": "button_click",
                },
            }
        ],
        text=f"Hey <@{message['user']}>!",  # fallback for notifications
    )

@app.action("button_click")
def handle_click(body, ack, say):
    ack()
    say(f"<@{body['user']['id']}> clicked the button")

Common Block Types

Common Interactive Elements

button, static_select, external_select, multi_static_select, datepicker, timepicker, checkboxes, radio_buttons, plain_text_input, number_input, email_text_input, url_text_input, overflow, file_input

Opening Modals

@app.command("/feedback")
def open_feedback_modal(ack, body, client):
    ack()
    client.views_open(
        trigger_id=body["trigger_id"],
        view={
            "type": "modal",
            "callback_id": "feedback_modal",
            "title": {"type": "plain_text", "text": "Feedback"},
            "submit": {"type": "plain_text", "text": "Submit"},
            "blocks": [
                {
                    "type": "input",
                    "block_id": "feedback_input",
                    "label": {"type": "plain_text", "text": "Your feedback"},
                    "element": {
                        "type": "plain_text_input",
                        "action_id": "feedback_text",
                        "multiline": True,
                    },
                }
            ],
        },
    )

@app.view("feedback_modal")
def handle_feedback(ack, body, client, view):
    feedback = view["state"]["values"]["feedback_input"]["feedback_text"]["value"]
    user = body["user"]["id"]
    # Validate
    errors = {}
    if len(feedback) < 10:
        errors["feedback_input"] = "Please write at least 10 characters"
    if errors:
        ack(response_action="errors", errors=errors)
        return
    ack()
    client.chat_postMessage(channel=user, text=f"Thanks for your feedback: {feedback}")

Key modal operations:

• client.views_open(trigger_id, view) — Open a new modal (trigger_id valid for 3 seconds)
• client.views_update(view_id, hash, view) — Update an existing modal
• client.views_push(trigger_id, view) — Push a new view onto the modal stack (max 2 pushes)

Access submitted values: view["state"]["values"][block_id][action_id]

Event Subscriptions

Subscribe to events in your app configuration. Common events:

Event Subtypes

@app.event({"type": "message", "subtype": "message_changed"})
def log_edit(logger, event):
    logger.info(f"Message edited: {event['text']}")

Common Scopes

Best Practices

1. Always ack() first — Call ack() immediately in commands/actions/shortcuts before doing work
2. Use Socket Mode for development — No public URL needed, simpler setup
3. Use environment variables for tokens — Never hardcode xoxb-, xoxp-, or xapp- tokens
4. Provide text fallback — When using blocks, always include a text parameter for notification previews
5. Handle errors — Wrap API calls in try/except for SlackApiError
6. Use Block Kit Builder — Design interactive layouts at https://app.slack.com/block-kit-builder
7. Request minimal scopes — Only request the permissions your app actually needs
8. Use lazy listeners for FaaS — Set process_before_response=True and use lazy=[] for serverless