django-slack-events-api is a minimal Django app for making your Slack bot.
It includes a Django porting of the official Slack Events API adapter: python-slack-events-api. The original adapter is based on the Flask framework; so here's a modular Django app version instead ;-)
This is intended to be minimal (devoid of extra model, template, and module-dependency stuff) focusing only on Slack Events handling. However, all the features and examples useful for Slack bot creation (such as utilizing the python-slackclient) found in the original Flask version are retained and functional. After working through the demo section, you'll find it easy to integrate this app into your Django projects as well.
Bonus: Additionally, django-slack-events-api supports three kinds of Slack client library integration:
- the official Slack Developer Kit for Python (aka. python-slackclient) [default],
- the popular slacker client, and
- a minimal client based on urllib2 (compatible with Google App Engine thanks to no socket module dependency).
Credits: Sections marked by 🤖 are a derived work of python-slack-events-api/example/README.rst.
Environment:
- Python 2.7
- Django 1.11.x
Install the app and its dependencies:
$ git clone https://github.com/j-devel/django-slack-events-api.git $ cd django-slack-events-api $ pipenv install $ pipenv shell
In this section, we present a quick demo on how to get a working Django-based Slack bot on your local computer. We create a new Django app from scratch and embed the django-slack app in it. After configurations, we start the Django local server on port 3000. ngrok is used to make sure that the local bot instance is properly communicating with the Slack server on the Internet.
(1) A new django project with a django slack app embedded
$ django-admin startproject bot # create a new django project called "bot" $ cp -r slack bot/ # copy (embed) the bare django-slack app under the bot project $ cd bot # move into the root of the bot project
Now the current directory structure should look as follows:
$ find . . # Root of the new "bot" project ./bot ./bot/__init__.py ./bot/settings.py # to be modified ./bot/urls.py # to be modified ./bot/wsgi.py ./manage.py ./slack # a copy of django-slack app ./slack/__init__.py ./slack/adapter_slackclient.py ./slack/adapter_slacker.py ./slack/adapter_urllib2.py ./slack/client_urllib2.py ./slack/urls.py ./slack/views.py
(2) Modify bot/settings.py to add the slack app and tokens.
For obtaining the SLACK_VERIFICATION_TOKEN and SLACK_BOT_TOKEN tokens,
see Appendix: Setup your bot in Slack.
INSTALLED_APPS = (
'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',
'slack', # <-- add this
)
SLACK_VERIFICATION_TOKEN = "xxxxxxxxXxxXxxXxXXXxxXxxx" # <-- add this
SLACK_BOT_TOKEN = "xxxXXxxXXxXXxXXXXxxxX.xXxxxXxxxx" # <-- add this
(3) Modify bot/urls.py to configure the endpoint.
from django.conf.urls import url, include # <-- add this
from django.contrib import admin
from slack import urls as slack_urls # <-- add this
urlpatterns = [
url(r'^admin/', admin.site.urls),
url(r'^slack/', include(slack_urls, namespace="slack")), # <-- add this
]
(4) [Optional] Modify slack/urls.py to customize the endpoint (default is /slack/events)
(5) [Optional] Select the underlying bot client library
In slack/views.py, uncomment the adapter corresponding to the client
library of your choice. (Unmodified, adapter_slackclient.py is used by
default.)
# uncomment for the slackclient API client (https://github.com/slackapi/python-slackclient) from .adapter_slackclient import slack_events_adapter, SLACK_VERIFICATION_TOKEN #---- # uncomment for the slacker API client (https://github.com/os/slacker) # from .adapter_slacker import slack_events_adapter, SLACK_VERIFICATION_TOKEN #---- # uncomment for a urllib2-based client implemented in client_urllib2.py # This should work with Google App Engine. # from .adapter_urllib2 import slack_events_adapter, SLACK_VERIFICATION_TOKEN
Depending on your choice of the client library, start hacking your bot's logic by editing one of
adapter_slackclient.py(using python-slackclient),adapter_slacker.py(using slacker), andadapter_urllib2.py(using slack/client_urllib2.py).
(6) 🤖 Start ngrok
In order for Slack to contact your local server, you'll need to run a tunnel. We recommend ngrok or localtunnel. We're going to use ngrok for this example.
If you don't have ngrok, download it here.
Here's a rudimentary diagream of how ngrok allows Slack to connect to your server
- 💡 Slack requires event requests be delivered over SSL, so you'll want to
- use the HTTPS URL provided by ngrok.
Run ngrok and copy the HTTPS URL
ngrok http 3000
ngrok by @inconshreveable (Ctrl+C to quit) Session status online Version 2.1.18 Region United States (us) Web Interface http://127.0.0.1:4040 Forwarding http://h7465j.ngrok.io -> localhost:9292 Forwarding https://h7465j.ngrok.io -> localhost:9292
(7) 🤖 Run the app
You'll need to have your server and ngrok running to complete your app's Event Subscription setup
$ python manage.py runserver 0.0.0.0:3000
🎉 Once your app has been installed and subscribed to Bot Events, you will begin receiving event data from Slack
(8) Interact with your bot
Invite your bot to a public channel (e.g. # general), then say hi and your bot will respond.
Here are Django console logs showing the interaction with the Slack server.
Case: local server + ngrok:
Case: Google App Engine:
🤖 Create a Slack app
Create a Slack app on https://api.slack.com/apps/
🤖 Add a bot user to your app
🤖 Install your app on your team
Visit your app's Install App page and click Install App to Team.
Authorize your app
🤖 Subscribe your app to events
Add your Request URL (your ngrok URL + /slack/events) and subscribe your app to message.channels under bot events. Save and toggle Enable Events to on
🤖 Save your app's credentials
Once you've authorized your app, you'll be presented with your app's tokens.
Copy your app's Bot User OAuth Access Token, then add the token in bot/settings.py.
SLACK_BOT_TOKEN = "xxxXXxxXXxXXxXXXXxxxX.xXxxxXxxxx"
Next, go back to your app's Basic Information page
Copy your app's Verification Token, then add the token in bot/settings.py.
SLACK_VERIFICATION_TOKEN = "xxxxxxxxXxxXxxXxXXXxxXxxx"