Simple Slack Bot makes writing your next Slack bot incredibly easy. By factoring out common functionality all Slack Bots require, you can focus on writing your business logic.
Run:
$ pip3 install simple_slack_bot
To install, simply clone the source, which will allow you to import SimpleSlackBot.
To configure, set a single environment variable
SLACK_BOT_TOKEN with your Slack Bot's API token
To generate or locate your Slack Bot Token, visit
https://[YOUR SLACK TEAM NAME HERE].slack.com/apps/manage/custom-integrations
and click
Bots
If you already have a bot created, you should see it listed here, otherwise you should be able to click
Add Configuration
to create one.
Once you have a bot find it listed in the configurations and click the
Edit
icon. You'll be brought to a page that lists your API token. This is what you'll use with Simple Slack Bot.
For full examples, see the examples directory
To integrate with Simple Slack Bot, simply create an instance of it and register for notifications using a Python decorator.
This can be seen with the following code below. Our Simple Slack Bot will reply to every message of "Ping", with "Pong", to every channel it's a part of:
ping_pong.py
from simple_slack_bot.simple_slack_bot import SimpleSlackBot
simple_slack_bot = SimpleSlackBot(debug=True)
@simple_slack_bot.register("message")
def pong_callback(request):
if request.message and request.message.lower() == "ping":
request.write("Pong")
def main():
simple_slack_bot.start()
if __name__ == "__main__":
main()At this point, your callback functions will be executed every time Simple Slack Bot receives the appropriate event.
Note: Simple Slack Bot can be initialized with debug mode turned on, which will display all debug messages out to stdout and stderr.
To enable this simply pass debug=True when initializing Simple Slack Bot. As seen below:
simple_slack_bot = SimpleSlackBot(debug=True)If you want more control on the routing of your logging, instead of passing debug=True when initializing Simple Slack Bot, you can configure the global logging variable in your own application.
An example:
import logging
from simple_slack_bot.simple_slack_bot import SimpleSlackBot
dict_config = {
'version': 1,
'disable_existing_loggers': False,
'formatters': {
'standard': {
'format': '%(asctime)s [%(levelname)s] %(name)s: %(message)s'
},
},
'handlers': {
'default': {
'level': 'INFO',
'formatter': 'standard',
'class': 'logging.StreamHandler',
},
},
'loggers': {
'': {
'handlers': ['default'],
'level': 'INFO',
'propagate': True
},
'django.request': {
'handlers': ['default'],
'level': 'WARN',
'propagate': False
},
}
}
simple_slack_bot = SimpleSlackBot()
logging.config.dictConfig(dict_config)
Where you'd create your own dictConfig based on your own needs.
Simple Slack Bot handles all of the parsing and routing of Slack events. To be informed of new slack events, you must register a callback function with Simple Slack Bot for each event. All Slack Events are registered to and can be seen here.
Each method you decorate in your Simple Slack Bot will need to take in a request. The contents of the request will differ depending on the event(s) you register to.
For each event you register for, take a look at the event here, as this is where the contents of the request will be defined.
For convenience, I've added the following attributes to all request objects:
type- type of eventchannel- the channel from the underlying SlackEvent- Note: This can be an empty String. For example, this will be an empty String for the 'Hello' event.
message- the received message
Often times when writing a Slack Bot, you'll find yourself writing a few key functions that I found generic enough to include in Simple-Slack-Bot. The function names are pretty self explanatory but they are as follows:
helper_write(channel, content)- Writes a message to the channel as the bothelper_get_public_channel_ids()- Gets all public channel idshelper_get_private_channel_ids()- Gets all private channel idshelper_get_user_ids()- Gets all user idshelper_get_users_in_channel(channel_id)- Gets all users in a given channelhelper_name_to_channel_id(name)- Converts a channel name to its respected channel idhelper_user_name_to_user_id(name)- Converts a user name to its respected user idhelper_channel_id_to_channel_name(channel_id)- Converts a channel id to its respected channel namehelper_user_id_to_user_name(user_id)- Converts a user id to its respected user name
To gain access to these functions, simply call the appropriate function on your SimpleSlackBot instance.
If you have found that Simple Slack Bot does not provide everything you are looking for, you can gain access to the underlying python Slack Client or SlackSocket object.
If you want to run the local version of Simple Slack Bot and not the verison you downloaded through PyPi, you can run the following in the Simple-Slack-Bot directory:
python3 setup.py install
and then import it as usual
from simple_slack_bot.simple_slack_bot import SimpleSlackBot.
You'll also have to install Simple Slack Bot's dependencies using PyPi. A requirements.txt will be kept up to date, along side the setup.py for this use case and your convenience.
The bot will only reply to channels that it is in. Don't forget to invite your bot into channels of interest!
To run the unit test suite, execute
$ make test
To generate code coverage of the unit test suite, execute:
$ make test-and-generate-coverage
We'll be maintaining a list of Simple Slack Bots here.
If you have written a Simple Slack Bot, please contact me to have yours added!
| Name | Author | Description |
|---|---|---|
| Ping Pong Bot | Greg Hilston | Ping Pong Bot was created to act as an example of how easy it is to create a bot using the open source Simple-Slack-Bot framework. Ping-Pong-Bot will look at every message sent to the channels that it is in, waiting for the case insensitive message "Ping". Once received Ping-Pong-Bot will write back to the very same channel "Pong". |
| The Office Bot | Greg Hilston | The Office Bot will look at every message sent to the channels that,it is in, waiting for a mention of the name of a character in the show, The Office, specifically the US version. Once received, The-Office-Bot will write back a random line that this character had throughout the show, including lines from deleted scenes. |
| Stan Bot | Jahir Fiquitiva | Stan Bot is a bot to help one with the SCRUM stand-up process. |
| Dice Bot | Greg Hilston | Dice Bot is used to perform simple dice rolls |
| DnD Bot | Greg Hilston | D and D Bot is used record small D&D sessions that take place in Slack, by recording the in game chat to a csv |