The Slack App is used to serve Agents or Teams via Slack, using a FastAPI server to handle Slack events and send messages.

​
Setup Steps

​
Setup and Configuration

1

Prerequisites

Ensure you have the following:

  • A Slack workspace with admin privileges
  • ngrok (for development)
  • Python 3.7+
2

Create a Slack App

  1. Go to Slack App Directory
  2. Click "Create New App"
  3. Select "From scratch"
  4. Provide:
    • App name
    • Workspace to install to
  5. Click "Create App"
3

Configure OAuth & Permissions

  1. Navigate to "OAuth & Permissions" in your Slack App settings
  2. Under "Scopes", click "Add an OAuth Scope"
  3. Add the following Bot Token Scopes:
    • app_mention
    • chat:write
    • chat:write.customize
    • chat:write.public
    • im:history
    • im:read
    • im:write
  4. Scroll to the top and click "Install to Workspace"
  5. Click "Allow" to authorize the app
4

Setup Environment Variables

Create a .envrc file in your project root with the following content, replacing placeholder values with your actual credentials:

export SLACK_TOKEN="xoxb-your-bot-user-token"  # Bot User OAuth Token
export SLACK_SIGNING_SECRET="your-signing-secret"  # App Signing Secret

Find these values in your Slack App settings:

  • Bot User OAuth Token: Under "OAuth & Permissions"
  • Signing Secret: Under "Basic Information" > "App Credentials"

Ensure this file is sourced by your shell (e.g., by using direnv allow).

5

Setup Webhook with ngrok

  1. For local development, use ngrok to expose your local server to the internet: 
    ngrok http 8000
# Or, if you have a paid ngrok plan with a static domain:
# ngrok http --domain=your-custom-domain.ngrok-free.app 8000
  2. Copy the https:// URL provided by ngrok
  3. In your Slack App settings, go to "Event Subscriptions"
  4. Enable events by toggling the switch
  5. Add your Request URL:
    • Format: https://your-ngrok-url.ngrok.io/slack/events
  6. Wait for Slack to verify the endpoint (your app must be running)
6

Configure Event Subscriptions

  1. Under "Subscribe to bot events" in Event Subscriptions:
  2. Click "Add Bot User Event" and add:
    • app_mention
    • message.im
    • message.channels
    • message.groups
  3. Click "Save Changes"
  4. Reinstall your app to apply the new permissions
7

Enable App Home

  1. Go to "App Home" in your Slack App settings
  2. Under "Show Tabs":
    • Enable "Messages Tab"
    • Check "Allow users to send Slash commands and messages from the messages tab"
  3. Save changes
8

Final Installation

  1. Go back to "Install App" in your Slack App settings
  2. Click "Reinstall to Workspace"
  3. Authorize the app with the new permissions
  4. Your app is now ready to use!

​
Example Usage

Create an agent, wrap it with SlackAPI, and serve it:

from agno.agent import Agent
from agno.app.slack.app import SlackAPI
from agno.models.openai import OpenAIChat

basic_agent = Agent(
    name="Basic Agent",
    model=OpenAIChat(id="gpt-4o"), # Ensure OPENAI_API_KEY is set
    add_history_to_messages=True,
    num_history_responses=3,
    add_datetime_to_instructions=True,
)

slack_api_app = SlackAPI(
    agent=basic_agent,
)
app = slack_api_app.get_app()

if __name__ == "__main__":
    slack_api_app.serve("basic:app", port=8000, reload=True)

​
Core Components

  • SlackAPI: Wraps Agno agents/teams for Slack integration via FastAPI.
  • SlackAPI.serve: Serves the FastAPI app using Uvicorn, configured for Slack.

​
SlackAPI Class

Main entry point for Agno Slack applications.

​
Initialization Parameters

ParameterTypeDefaultDescription
agentOptional[Agent]NoneAgno Agent instance.
teamOptional[Team]NoneAgno Team instance.
settingsOptional[APIAppSettings]NoneAPI configuration. Defaults if None.
api_appOptional[FastAPI]NoneExisting FastAPI app. New one created if None.
routerOptional[APIRouter]NoneExisting APIRouter. New one created if None.
app_idOptional[str]NoneApp identifier (autogenerated if not set).
nameOptional[str]NoneName for the App.
descriptionOptional[str]NoneDescription for the App.

Provide agent or team, not both.

​
Endpoints

The main endpoint for Slack integration:

​
POST /slack/events

  • Description: Handles all Slack events including messages and app mentions
  • Security: Verifies Slack signature for each request
  • Event Types:
    • URL verification challenges
    • Message events
    • App mention events
  • Features:
    • Threaded conversations
    • Background task processing
    • Message splitting for long responses
    • Support for both direct messages and channel interactions

​
Testing the Integration

  1. Start your application locally with python <my-app>.py (ensure ngrok is running)
  2. Invite the bot to a channel using /invite @YourAppName
  3. Try mentioning the bot in the channel: @YourAppName hello
  4. Test direct messages by opening a DM with the bot

​
Troubleshooting

  • Verify all environment variables are set correctly
  • Ensure the bot has proper permissions and is invited to channels
  • Check ngrok connection and URL configuration
  • Verify event subscriptions are properly configured
  • Monitor application logs for detailed error messages

​
Support

For additional help or to report issues, please refer to the documentation or open an issue in the repository.