Bridge between Slack and Channels-based Django apps
Project description
# Djangobot
Djangobot is a bridge between Slack and a [Channels](https://channels.readthedocs.org)-enabled Django app.
Specifically, it is a protocol server that produces and consumes messages for channels-based apps.
It is built atop [autobahn](http://autobahn.ws/python/) and [twisted](http://twistedmatrix.com/trac/).
## Installation & Usage
To install, simply use pip.
```shell
$ pip install djangobot
```
Djangobot should be installed in the virtual environment of your application as it needs to be able to import one of the specified channel layers defined in your `settings.py`.
Then, assuming your django project is named `myapp`, the ASGI file is named `asgi.py` and you've created a channel layer in it named `channel_layer`, run this command:
```shell
$ DJANGOBOT_TOKEN=[your slack token] djangobot myapp.asgi:channel_layer
```
In production, you'll want to keep this process alive with [supervisor](http://supervisord.org/), [circus](https://circus.readthedocs.org/en/latest/) or a similar tool.
## What's it doing?
When beginning `djangobot`, it will:
1. Connect to the Slack API and request users and channels for your team.
2. Initiate a [Real-Time Messaging Connection](https://api.slack.com/rtm).
3. Forward any RTM events onto the `slack.{type}` channel. For example, message events
(whose `type` is `message`) are sent along the `slack.message` channel.
4. Send any messages on the `slack.send` channel back to slack.
## Receiving events in your application
In your `routing.py`, you'll need to specify consumer functions to handle events on the slack
channels like so:
```python
channel_routing = {
'websocket.receive': 'path.to.my.consumer',
'websocket.connect': 'path.to.another.consumer',
'websocket.disconnect': 'path.to.yet.another.consumer',
# Slack channels
'slack.message': 'function.to.handle.slack.messages',
'slack.hello': 'handle.when.djangobot.connects',
# and so forth
```
## Sending messages to slack
To send messages to slack, simply send a dictionary at least a `text` key. You may optionally include the `channel` on which to post the message. This can be the human-readable version or a channel id. Note that `djangobot` necessarily posts messages as the user tied to your Slack API token.
For example:
```python
import channels
channels.Channel('slack.send').send({'text': 'Why hello there!', 'channel': 'general'})
Of course, part of the beauty of channels is that this can be done from anywhere.
# Why is this useful?
This simply bridges your slack team to your production application in real-time. On it's own, it does nothing else. Implementing actual features is up to you. Off the top of my head, some ideas:
1. Make Slack a logging destination.
2. 2FA to approve certain tasks.
3. Chat through Slack to users.
# Contributing
1. Fork this repository.
2. Create a branch with your feature or bug fix.
3. Work on it, push commits.
4. Submit a Pull Request.
# Todo
1. Testing: I would appreciate help testing twisted clients.
2. Setting up the reply channel: Right now the
2. Logging: Djangobot could `logger.debug` a lot more.
Djangobot is a bridge between Slack and a [Channels](https://channels.readthedocs.org)-enabled Django app.
Specifically, it is a protocol server that produces and consumes messages for channels-based apps.
It is built atop [autobahn](http://autobahn.ws/python/) and [twisted](http://twistedmatrix.com/trac/).
## Installation & Usage
To install, simply use pip.
```shell
$ pip install djangobot
```
Djangobot should be installed in the virtual environment of your application as it needs to be able to import one of the specified channel layers defined in your `settings.py`.
Then, assuming your django project is named `myapp`, the ASGI file is named `asgi.py` and you've created a channel layer in it named `channel_layer`, run this command:
```shell
$ DJANGOBOT_TOKEN=[your slack token] djangobot myapp.asgi:channel_layer
```
In production, you'll want to keep this process alive with [supervisor](http://supervisord.org/), [circus](https://circus.readthedocs.org/en/latest/) or a similar tool.
## What's it doing?
When beginning `djangobot`, it will:
1. Connect to the Slack API and request users and channels for your team.
2. Initiate a [Real-Time Messaging Connection](https://api.slack.com/rtm).
3. Forward any RTM events onto the `slack.{type}` channel. For example, message events
(whose `type` is `message`) are sent along the `slack.message` channel.
4. Send any messages on the `slack.send` channel back to slack.
## Receiving events in your application
In your `routing.py`, you'll need to specify consumer functions to handle events on the slack
channels like so:
```python
channel_routing = {
'websocket.receive': 'path.to.my.consumer',
'websocket.connect': 'path.to.another.consumer',
'websocket.disconnect': 'path.to.yet.another.consumer',
# Slack channels
'slack.message': 'function.to.handle.slack.messages',
'slack.hello': 'handle.when.djangobot.connects',
# and so forth
```
## Sending messages to slack
To send messages to slack, simply send a dictionary at least a `text` key. You may optionally include the `channel` on which to post the message. This can be the human-readable version or a channel id. Note that `djangobot` necessarily posts messages as the user tied to your Slack API token.
For example:
```python
import channels
channels.Channel('slack.send').send({'text': 'Why hello there!', 'channel': 'general'})
Of course, part of the beauty of channels is that this can be done from anywhere.
# Why is this useful?
This simply bridges your slack team to your production application in real-time. On it's own, it does nothing else. Implementing actual features is up to you. Off the top of my head, some ideas:
1. Make Slack a logging destination.
2. 2FA to approve certain tasks.
3. Chat through Slack to users.
# Contributing
1. Fork this repository.
2. Create a branch with your feature or bug fix.
3. Work on it, push commits.
4. Submit a Pull Request.
# Todo
1. Testing: I would appreciate help testing twisted clients.
2. Setting up the reply channel: Right now the
2. Logging: Djangobot could `logger.debug` a lot more.
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
djangobot-0.1.tar.gz
(5.9 kB
view hashes)
Built Distributions
Close
Hashes for djangobot-0.1.macosx-10.10-x86_64.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | b7a293ee46406eec32243b4350740caea5bc13a151b321bfdf52777fa37a6128 |
|
MD5 | 8e44e61956b2cedf467952cb36107fc5 |
|
BLAKE2b-256 | b135df94ef550b808eed33deff746b97f47564573f3da890d72e8c038ddce9d0 |
Close
Hashes for djangobot-0.1-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b3c02e57b57b82c8197e35c8f1707b7347d32d0e436205930f7f44f281b97bd1 |
|
MD5 | 21b0dcf695f2656f676bbfa71f0f6c65 |
|
BLAKE2b-256 | aa249eb240ec868f7bfaa8b503afb8c9bc3093ac7c8c1d6d23697386d6a30b50 |