Skip to main content

A simple chat bot for Slack

Project description


This is a fork of scrapinghub/slackbot due to the lack of the activity from the original author. Python package was renamed to slackbotng and it's being publishing to:

A chat bot for Slack inspired by llimllib/limbo and will.



pip install slackbotng


Generate the slack api token

First you need to get the slack api token for your bot. You have two options:

  1. If you use a bot user integration of slack, you can get the api token on the integration page.
  2. If you use a real slack user, you can generate an api token on slack web api page.

Configure the bot

First create a and a in your own instance of slackbot.

Configure the api token

Then you need to configure the API_TOKEN in a python module, which must be located in a python import path. This will be automatically imported by the bot.

API_TOKEN = "<your-api-token>"

Alternatively, you can use the environment variable SLACKBOT_API_TOKEN.

Run the bot
from import Bot
def main():
    bot = Bot()

if __name__ == "__main__":
Configure the default answer


DEFAULT_REPLY = "Sorry but I didn't understand you"
Configure the docs answer

The message attribute passed to your custom plugins has an special function message.docs_reply() that will parse all the plugins available and return the Docs in each of them.

Send all tracebacks directly to a channel, private channel, or user

Set ERRORS_TO in to the desired recipient. It can be any channel, private channel, or user. Note that the bot must already be in the channel. If a user is specified, ensure that they have sent at least one DM to the bot first.

ERRORS_TO = 'some_channel'
# or...
ERRORS_TO = 'username'
Configure the plugins

Add your plugin modules to a PLUGINS list in


Now you can talk to your bot in your slack client!

Attachment Support

from import respond_to
import re
import json

@respond_to('github', re.IGNORECASE)
def github(message):
    attachments = [
        'fallback': 'Fallback text',
        'author_name': 'Author',
        'author_link': '',
        'text': 'Some text',
        'color': '#59afe1'
    message.send_webapi('', json.dumps(attachments))

Create Plugins

A chat bot is meaningless unless you can extend/customize it to fit your own use cases.

To write a new plugin, simply create a function decorated by,,

  • A function decorated with respond_to is called when a message matching the pattern is sent to the bot (direct message or @botname in a channel/group chat)
  • A function decorated with listen_to is called when a message matching the pattern is sent on a channel/group chat (not directly sent to the bot)
  • A function decorated with run_at_times is called periodically at a given amount of seconds
from import respond_to, listen_to, run_at_times
import re

@respond_to('hi', re.IGNORECASE)
def hi(message):
    message.reply('I can understand hi or HI!')
    # react with thumb up emoji

@respond_to('I love you')
def love(message):
    message.reply('I love you too!')

@listen_to('Can someone help me?')
def help(message):
    # Message is replied to the sender (prefixed with @user)
    message.reply('Yes, I can!')

    # Message is sent on the channel
    message.send('I can help everybody!')

    # Start a thread on the original message
    message.reply("Here's a threaded reply", in_thread=True)
def run_once_at_60s(client):
    client.rtm_send_message('channel_name_or_username', 'This runs once at 60s!')

To extract params from the message, you can use regular expression:

from import respond_to

@respond_to('Give me (.*)')
def giveme(message, something):
    message.reply('Here is {}'.format(something))

If you would like to have a command like 'stats' and 'stats start_date end_date', you can create reg ex like so:

from import respond_to
import re

@respond_to('stat$', re.IGNORECASE)
@respond_to('stat (.*) (.*)', re.IGNORECASE)
def stats(message, start_date=None, end_date=None):

And add the plugins module to PLUGINS list of slackbot settings, e.g.


The @default_reply decorator

Added in slackbot 0.4.1

Besides specifying DEFAULT_REPLY in, you can also decorate a function with the @default_reply decorator to make it the default reply handler, which is more handy.

def my_default_handler(message):

Here is another variant of the decorator:

def my_default_handler(message):

The above default handler would only handle the messages which must (1) match the specified pattern and (2) can't be handled by any other registered handler.

List of third party plugins

You can find a list of the available third party plugins on this page.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

slackbotng-1.1.2.tar.gz (16.1 kB view hashes)

Uploaded source

Built Distribution

slackbotng-1.1.2-py2.py3-none-any.whl (16.2 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page