Slack Bot

This guide shows how to create a Slack bot using Timbal that can:

Respond to messages in real-time via webhooks
Process user requests intelligently with AI agents
Handle threaded conversations

Setup Requirements

Installing Packages

Install the Slack SDK:

pip install slack-sdk

For all available Slack API methods and capabilities, see the Slack API Methods Reference.

Creating a Slack App

Create a Slack App

Go to Slack API and click Create New App
Choose From scratch
Enter your app name and select your workspace

Configure Bot Token Scopes

Go to OAuth & Permissions
Add the following Bot Token Scopes based on Timbal handlers you’ll use:

# Message Operations
chat:write            # Send messages
chat:write.public     # Send messages to channels bot isn't in
im:write             # Send direct messages

# Channel & Conversation Operations
channels:read        # View basic channel information
channels:history     # Get messages from channels
groups:read          # View basic private channel information
im:read              # View basic direct message information
im:history           # Get direct message history

# App Mentions & Reactions
app_mentions:read    # Receive app mention events
reactions:read       # Read message reactions

# File Operations
files:read           # Download files from Slack
files:write          # Upload files to Slack

After adding or modifying scopes, you’ll need to reinstall the app to your workspace for the changes to take effect.

Install App to Workspace

In OAuth & Permissions, click Install to Workspace
Copy the Bot User OAuth Token (starts with xoxb-)
Set as environment variable: SLACK_BOT_TOKEN

Enable Home Tab (for Direct Messages)

Go to App Home in your Slack app settings
Under Show Tabs, enable Home Tab
Check Allow users to send Slash commands and messages from the messages tab
This enables users to send direct messages to your bot

Get Bot User ID

In your Slack workspace, start a direct message with your bot
Click on the bot’s name at the top of the chat
In the profile panel, find the Member ID (format: U12345678)
Set this as environment variable: SLACK_BOT_USER_ID=U12345678

The Bot User ID is required to prevent infinite loops by filtering out the bot’s own messages.

Implementation

Setting up the Slack Bot Configuration

First, set up the Slack configuration with your bot’s user ID and authentication token. Create a .env file in your project root:

.env

SLACK_BOT_USER_ID=U12345678  # Your actual bot user ID
SLACK_BOT_TOKEN=xoxb-your-bot-token-here  # Your bot token

Then configure your Python code:

import os

from dotenv import load_dotenv
from slack_sdk import WebClient

# Load environment variables from .env
load_dotenv()

SLACK_BOT_USER_ID = os.getenv("SLACK_BOT_USER_ID")

client = WebClient(token=os.getenv("SLACK_BOT_TOKEN"))

Creating the Agent

Create the Timbal agent with pre and post hooks for Slack integration:

from timbal import Agent

agent = Agent(
    name="SlackAgent",
    system_prompt="You are a tech support AI assistant. Help users with their technical questions clearly and concisely.",
    model="openai/gpt-4.1-mini",
    pre_hook=pre_hook,
    post_hook=post_hook,
)

Pre-hook: Processing Incoming Messages

The pre-hook handles incoming Slack webhook events and extracts relevant information.

Parameter Name Flexibility: The _webhook parameter name is completely custom. You can use any name you prefer:

await agent(slack_data=body).collect()
await agent(webhook_payload=body).collect()
await agent(event_data=body).collect()

Just ensure the same name is used consistently in both the agent call and the pre_hook check.

from timbal.state import get_run_context
from timbal.errors import bail

async def pre_hook():
    """Process incoming Slack webhook events before agent execution."""
    span = get_run_context().current_span()

    # Check if this is a Slack webhook event
    # Note: "_webhook" matches the parameter name used when calling agent(_webhook=body)
    if "_webhook" not in span.input:
        return  # Not triggered by Slack

    slack_event = span.input["_webhook"]["event"]

    # Ignore bot's own messages to prevent infinite loops
    if slack_event.get("user") == SLACK_BOT_USER_ID:
        raise bail()

    # Extract and validate message text
    text = slack_event.get("text", "")
    if not text:
        raise bail()

    # Store Slack context for response
    span.slack_channel = slack_event["channel"]
    span.slack_thread_ts = slack_event.get("thread_ts")  # Reply in same thread
    span.input["prompt"] = text

Post-hook: Sending Responses

The post-hook sends the agent’s response back to Slack:

from timbal.state import get_run_context

def post_hook():
    """Send agent response back to Slack channel."""
    span = get_run_context().current_span()
    
    # Only process Slack webhook events
    if "_webhook" not in span.input:
        return

    # Extract response context
    slack_channel = span.slack_channel
    slack_thread_ts = span.slack_thread_ts
    reply = span.output.collect_text()

    # Send response if not empty
    if reply.strip():
        client.chat_postMessage(
            channel=slack_channel,
            text=reply,
            thread_ts=slack_thread_ts,
        )

Complete Example

Here’s the full implementation ready to use:

agent.py

import os

from dotenv import load_dotenv
from slack_sdk import WebClient
from timbal import Agent
from timbal.errors import bail
from timbal.state import get_run_context

# Load environment variables from .env
load_dotenv()

SLACK_BOT_USER_ID = os.getenv("SLACK_BOT_USER_ID")

client = WebClient(token=os.getenv("SLACK_BOT_TOKEN"))

async def pre_hook():
    """Process incoming Slack webhook events before agent execution."""
    span = get_run_context().current_span()

    # Only process Slack webhook events
    # Note: "_webhook" must match the parameter name used when calling agent(_webhook=body)
    if "_webhook" not in span.input:
        return

    slack_event = span.input["_webhook"]["event"]

    # Prevent infinite loops by ignoring bot's own messages
    if slack_event.get("user") == SLACK_BOT_USER_ID:
        raise bail()

    # Extract message text
    text = slack_event.get("text", "")
    if not text:
        raise bail()

    # Store context for response
    span.slack_channel = slack_event["channel"]
    span.slack_thread_ts = slack_event.get("thread_ts")
    span.input["prompt"] = text

def post_hook():
    """Send agent response back to Slack."""
    span = get_run_context().current_span()
    
    if "_webhook" not in span.input:
        return

    # Get response and send to Slack
    reply = span.output.collect_text()
    slack_channel = span.slack_channel
    slack_thread_ts = span.slack_thread_ts
    
    if reply.strip():
        client.chat_postMessage(
            channel=slack_channel,
            text=reply,
            thread_ts=slack_thread_ts,
        )

# Create the Slack agent
agent = Agent(
    name="SlackAgent",
    system_prompt="You are a tech support AI assistant. Help users with their technical questions clearly and concisely.",
    model="openai/gpt-4.1-mini",
    pre_hook=pre_hook,
    post_hook=post_hook,
)

Running the Agent

Timbal provides built-in ngrok integration for easy local development. To use this feature:

Set up ngrok account and authtoken

Create an account at ngrok.com
Install ngrok on your system and the Python package:

pip install pyngrok

Configure your authtoken:

ngrok config add-authtoken YOUR_AUTHTOKEN

Create FastAPI Webhook Handler

Create a simple FastAPI server to handle Slack’s URL verification and webhook events:

server.py

import uvicorn
from dotenv import load_dotenv
from fastapi import FastAPI, Request
from pyngrok import ngrok

# Import our Slack agent to handle webhook events
from agent import agent

load_dotenv()

app = FastAPI()

@app.post("/")
async def slack_events(request: Request):
    body = await request.json()
    
    if body.get("type") == "url_verification":
        return {"challenge": body.get("challenge")}
    
    # Process actual Slack events here
    if body.get("type") == "event_callback":
        await agent(_webhook=body).collect()  # _webhook is a custom parameter name you define
        
    return {"status": "ok"}

if __name__ == "__main__":
    port = 8000
    public_url = ngrok.connect(port, "http")
    print(f"Public URL: {public_url}")
    
    uvicorn.run(app, host="0.0.0.0", port=port)

Run the Server and Get ngrok URL

Run the script to start your Slack bot:

python server.py

Or using uv (recommended):

uv run server.py

Copy the ngrok public URL displayed in the terminal (e.g., https://abc123.ngrok-free.app)

Enable Event Subscriptions

Go to Event Subscriptions and toggle Enable Events
Set Request URL to our webhook endpoint (e.g., https://abc123.ngrok-free.app/)
Subscribe to Bot Events - these determine what events Slack will send to your bot:

message.channels  # Bot receives messages in public channels it's added to
message.groups    # Bot receives messages in private channels it's added to
message.im        # Bot receives direct messages sent to it
app_mention       # Bot receives messages that mention it (@botname)
reaction_added    # Bot receives events when reactions are added to messages

Your Slack bot is now ready! 🚀 Start a direct message with your bot or mention it in a channel to begin chatting with your AI assistant.

Key Features

Real-time Responses: Instantly processes Slack messages via webhooks
Thread Support: Maintains conversation context in Slack threads
Loop Prevention: Automatically ignores bot’s own messages
Flexible AI: Uses any LLM model supported by Timbal
Easy Integration: Minimal setup with existing Slack handlers

Troubleshooting

Bot Not Responding

Check webhook URL is publicly accessible and returns 200 status
Ensure bot has correct permissions in Slack workspace
Confirm SLACK_BOT_USER_ID matches your bot’s actual user ID
Test webhook endpoint manually with curl or Postman

Infinite Loop Issues

Double-check SLACK_BOT_USER_ID is correct (found in Slack app settings)
Ensure pre-hook properly filters bot messages with bail()
Verify webhook events aren’t being duplicated
Check that bot doesn’t respond to its own message events

Agent Not Processing Messages

Check that OpenAI API key is valid and has sufficient credits
Verify agent model name is correct (e.g., openai/gpt-4o-mini)
Ensure pre-hook is setting span.input["prompt"] correctly
Add logging to debug webhook payload structure

Server Won't Start

Ensure all required packages are installed (slack-sdk fastapi uvicorn pyngrok python-dotenv)
Verify ngrok is installed and configured with authtoken
Make sure port 8000 is not already in use by another process
Ensure Slack Request URL matches your POST endpoint route with ”/” (e.g., https://abc123.ngrok-free.app/)

Examples

Guides

Agents

Workflows

Setup Requirements

Implementation

Setting up the Slack Bot Configuration

Creating the Agent

Pre-hook: Processing Incoming Messages

Post-hook: Sending Responses

Complete Example

Running the Agent

Key Features

Troubleshooting

​Setup Requirements

​Implementation

​Setting up the Slack Bot Configuration

​Creating the Agent

​Pre-hook: Processing Incoming Messages

​Post-hook: Sending Responses

​Complete Example

​Running the Agent

​Key Features

​Troubleshooting

Setup Requirements

Implementation

Setting up the Slack Bot Configuration

Creating the Agent

Pre-hook: Processing Incoming Messages

Post-hook: Sending Responses

Complete Example

Running the Agent

Key Features

Troubleshooting