A chat bot for Slack inspired by llimllib/limbo and will.
- Based on slack Real Time Messaging API
- Simple plugins mechanism
- Messages can be handled concurrently
- Automatically reconnect to slack when connection is lost
- Python3 Support
- Full-fledged functional tests
sudo pip install slackbot
First you need to get the slack api token for your bot. You have two options:
- If you use a bot user integration of slack, you can get the api token on the integration page.
- If you use a real slack user, you can generate an api token on slack web api page.
First create a slackbot_settings.py
and a run.py
in your own instance of slackbot.
Then you need to configure the API_TOKEN
in a python module slackbot_settings.py
, which must be located in a python import path. This will be automatically imported by the bot.
slackbot_settings.py:
API_TOKEN = "<your-api-token>"
Alternatively, you can use the environment variable SLACKBOT_API_TOKEN
.
from slackbot.bot import Bot
def main():
bot = Bot()
bot.run()
if __name__ == "__main__":
main()
Add a DEFAULT_REPLY to slackbot_settings.py
:
DEFAULT_REPLY = "Sorry but I didn't understand you"
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.
Set ERRORS_TO
in slackbot_settings.py
to the desired recipient. It can be any channel, group, 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'
Add your plugin modules to a PLUGINS
list in slackbot_settings.py
:
PLUGINS = [
'slackbot.plugins',
'mybot.plugins',
]
Now you can talk to your bot in your slack client!
from slackbot.bot import respond_to
import re
import json
@respond_to('github', re.IGNORECASE)
def github():
attachments = [
{
'fallback': 'Fallback text',
'author_name': 'Author',
'author_link': 'http://www.github.com',
'text': 'Some text',
'color': '#59afe1'
}]
message.send_webapi('', json.dumps(attachments))
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 slackbot.bot.respond_to
, slackbot.bot.listen_to
, or slackbot.bot.idle
:
- 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) - (development version only) A function decorated with
idle
is called whenever a message has not been sent for the past second
from slackbot.bot import respond_to, listen_to, idle
import re
@respond_to('hi', re.IGNORECASE)
def hi(message):
message.reply('I can understand hi or HI!')
# react with thumb up emoji
message.react('+1')
@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!')
last_bored = time.time()
@idle
def bored(client):
if time.time() - last_bored >= 30:
last_bored = time.time()
# Messages can be sent to a channel
client.rtm_send_message('some_channel', "I'm bored!")
# Or directly to a user
client.rtm_send_message('some_user', "Hey, entertain me!")
# If a name is ambiguous:
client.rtm_send_message(client.find_channel_by_name('ambiguous'), "To ambiguous the channel")
client.rtm_send_message(client.find_user_by_name('ambiguous'), "To ambiguous the user")
# Attachments can be sent with `client.rtm_send_message(..., attachments=attachments)`.
To extract params from the message, you can use regular expression:
from slackbot.bot 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 slackbot.bot 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. slackbot_settings.py:
PLUGINS = [
'slackbot.plugins',
'mybot.plugins',
]
added in slackbot 0.4.1
Besides specifying DEFAULT_REPLY
in slackbot_settings.py
, you can also decorate a function with the @default_reply
decorator to make it the default reply handler, which is more handy.
@default_reply
def my_default_hanlder(messsage):
message.reply('...')
Here is another variant of the decorator:
@default_reply(r'hello.*)')
def my_default_hanlder(messsage):
message.reply('...')
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 hanlder.
You can find a list of the available third party plugins on this page.