Slack Machine

Slack Machine is a simple, yet powerful and extendable Slack bot framework. More than just a bot, Slack Machine is a framework that helps you develop your Slack workspace into a ChatOps powerhouse. Slack Machine is built with an intuitive plugin system that lets you build bots quickly, but also allows for easy code organization. A plugin can look as simple as this:

from machine.plugins.base import MachineBasePlugin
from machine.plugins.message import Message
from machine.plugins.decorators import respond_to

class DeploymentPlugin(MachineBasePlugin):
    """Deployments"""

    @respond_to(r"deploy (?P<application>\w+) to (?P<environment>\w+)")
    async def deploy(self, msg: Message, application, environment):
        """deploy <application> <environment>: deploy application to target environment"""
        await msg.say(f"Deploying {application} to {environment}")

Breaking Changes

Plugin initialization is now async (v0.35.0)

The optional initialization method plugins can implement, which is run once when the plugin is loaded, should be an async method starting the upcoming v0.35.0. The reason for this is that this allows plugins to interact with Slack through the Slack Machine's plugin API - most of which methods are async.

Simply prefix your init() methods with async.

Dropped support for Python 3.7 (v0.34.0)

As of v0.34.0, support for Python 3.7 has been dropped. Python 3.7 has reached end-of-life on 2023-06-27.

AsyncIO (v0.30.0)

As of v0.30.0 Slack Machine dropped support for the old backend based on the RTM API. As such, Slack Machine is now fully based on AsyncIO. This means plugins written before the rewrite to asyncio aren't supported anymore. See here for a migration guide to get your old plugins working with the new version of Slack Machine.

It's really easy!

Features

Get started with mininal configuration
Built on top of the Slack Events API for smoothly responding to events in semi real-time. Uses Socket Mode so your bot doesn't need to be exposed to the internet!
Support for rich interactions using the Slack Web API
High-level API for maximum convenience when building plugins
Low-level API for maximum flexibility
Built on top of AsyncIO to ensure good performance by handling communication with Slack concurrently

Plugin API features:

Listen and respond to any regular expression
Respond to Slash Commands
Capture parts of messages to use as variables in your functions
Respond to messages in channels, groups and direct message conversations
Respond with reactions
Respond in threads
Respond with ephemeral messages
Send DMs to any user
Support for blocks
Support for message attachments [Legacy 🏚]
Support for interactive elements
Listen and respond to any Slack event supported by the Events API
Store and retrieve any kind of data in persistent storage (currently Redis, DynamoDB, SQLite and in-memory storage are supported)
Schedule actions and messages
Emit and listen for events
Help texts for Plugins

Coming Soon

Support for modals
Support for shortcuts
... and much more

Installation

You can install Slack Machine using pip:

$ pip install slack-machine

or add it to your Poetry project:

poetry add slack-machine

It is strongly recommended that you install slack-machine inside a virtual environment!

Usage

Create a directory for your Slack Machine bot: mkdir my-slack-bot && cd my-slack-bot
Add a local_settings.py file to your bot directory: touch local_settings.py
Create a new app in Slack: https://api.slack.com/apps
Choose to create an app from an App manifest
Copy/paste the following manifest: manifest.yaml

Add the Slack App and Bot tokens to your local_settings.py like this:

SLACK_APP_TOKEN = "xapp-my-app-token"
SLACK_BOT_TOKEN = "xoxb-my-bot-token"

Start the bot with slack-machine
...
Profit!

Documentation

You can find the documentation for Slack Machine here: https://dondebonair.github.io/slack-machine/

Go read it to learn how to properly configure Slack Machine, write plugins, and more!

DonDebonair / slack-machine

readme