Simple Slack Bot makes writing your next Slack bot incredibly easy
Project description
Simple Slack Bot
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.
Installing
Pip
Run:
$ pip3 install simple_slack_bot
From Source
To install, simply clone the source, which will allow you to import SimpleSlackBot.
Configuration
To configure, set a single environment variable
SLACK_BOT_TOKEN
with your Slack Bot's API token
Finding Your Slack Bot 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.
Example
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.
A repo of this example Ping Pong Bot can be found here. Feel free to use it as a reference or fork it as a stating point!
Debug Mode
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)
Additional Logging Control
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.
Supported Events
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.
The request
Object
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
Helper Functions & Callbacks Making Callbacks
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.
Writing More Advanced Slack Bots
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.
Running Local Development Version
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.
Unit Tests
To run the unit test suite, execute
$ make test
To generate code coverage of the unit test suite, execute:
$ make test-and-generate-coverage
Simple Slack Bots
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 gmae chat to a csv |
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for simple_slack_bot-2.3.4-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 025afff9000c3ebf92dae6d53608ab502cbdd0e57895aaacf49633e949bf2d05 |
|
MD5 | 04f81ea9a87087615f35d7776a1f04e8 |
|
BLAKE2b-256 | 6cf4bc3bf9a912bda98bcf947187e9031b02369331a45925759f7d5dfb2891d5 |