mirror of https://github.com/zulip/zulip.git
217 lines
8.0 KiB
Markdown
217 lines
8.0 KiB
Markdown
# Running bots in Zulip
|
|
|
|
Zulip's features can be extended by the means of bots and integrations.
|
|
|
|
* **Integrations** are used to connect Zulip with different chat, scheduling and workflow software.
|
|
If this is what you are looking for, please check out the [integrations guide](
|
|
http://zulip.readthedocs.io/en/latest/integration-guide.html?highlight=integrations).
|
|
* **Bots**, as a more general concept, intercept and react to messages.
|
|
If this is what you are looking for, read on!
|
|
|
|
The purpose of this documentation is to provide you with information about Zulip's
|
|
bot system.
|
|
|
|
On this page you'll find:
|
|
|
|
* A step-by-step [tutorial](#how-to-run-a-bot) on how to run a bot.
|
|
* Common [problems](#common-problems) when developing/running bots and their solutions.
|
|
|
|
Contributions to this guide are very welcome, so if you run into any
|
|
issues following these instructions or come up with any tips or tools
|
|
that help with writing bots, please visit
|
|
[#integrations](https://chat.zulip.org/#narrow/stream/integrations) on the
|
|
[Zulip development community server](https://chat.zulip.org), open an
|
|
issue, or submit a pull request to share your ideas!
|
|
|
|
## Installing the `zulip_bots` package
|
|
|
|
The `zulip_bots` package comes with all you need to run a bot.
|
|
|
|
To install it, run `pip install zulip_bots`.
|
|
|
|
|
|
## How to run a bot
|
|
|
|
This guide will show you how to run a bot on a running Zulip
|
|
server. It assumes you want to use one of the existing `zulip_bots/bots`
|
|
bots in your Zulip organization.
|
|
|
|
*Looking for an easy way to test a bot's output? Check out [this](
|
|
#testing-a-bot-s-output) section.*
|
|
|
|
You need:
|
|
|
|
* An account in an organization on a Zulip server
|
|
(e.g. [chat.zulip.org](https://chat.zulip.org) or
|
|
yourSubdomain.zulipchat.com, or your own development server).
|
|
Within that Zulip organization, users will be able to interact with
|
|
your bot.
|
|
* A computer where you're running the bot from.
|
|
|
|
**Note: Please be considerate when testing experimental bots on
|
|
public servers such as chat.zulip.org.**
|
|
|
|
1. [Install all requirements](#installing-the-zulip-bots-package).
|
|
|
|
2. Register a new bot user on the Zulip server's web interface.
|
|
|
|
* Log in to the Zulip server.
|
|
* Navigate to *Settings (<i class="fa fa-cog"></i>)* -> *Your bots* -> *Add a new bot*.
|
|
Select *Generic bot* for bot type, fill out the form and click on *Create bot*.
|
|
* A new bot user should appear in the *Active bots* panel.
|
|
|
|
3. Download the bot's `.zuliprc` configuration file to your computer.
|
|
|
|
* In the *Active bots* panel, click on the little green download icon
|
|
to download its configuration file *.zuliprc* (the structure of this file is
|
|
explained [here](#configuration-file)).
|
|
* Copy the file to a destination of your choice, e.g. to `~/.zuliprc`.
|
|
|
|
4. Run the bot.
|
|
|
|
* Run
|
|
```
|
|
zulip-run-bot <bot-name> --config-file ~/.zuliprc
|
|
```
|
|
(using the path to the `.zuliprc` file from step 3).
|
|
* Check the output of the command. It should start with the text
|
|
the `usage` function returns, followed by logging output similar
|
|
to this:
|
|
|
|
```
|
|
INFO:root:starting message handling...
|
|
INFO:requests.packages.urllib3.connectionpool:Starting new HTTP connection (1): localhost
|
|
```
|
|
|
|
* Congrats! Now, your bot should be ready to test.
|
|
|
|
### Testing the helloworld bot
|
|
|
|
* The `helloworld` bot is a simple bot that responds with a 'beep boop'
|
|
when queried. It can be used as a template to build more complex
|
|
bots.
|
|
* In a stream and topic of your choice, type `@<your bot name>`.
|
|
The `helloworld` bot should respond with "beep boop".
|
|
|
|
## Zulip Botserver
|
|
|
|
The Zulip Botserver is for people who want to
|
|
|
|
* run bots in production.
|
|
* run multiple bots at once.
|
|
|
|
The Zulip Botserver is a Python (Flask) server that implements Zulip's
|
|
Outgoing Webhooks API. You can of course write your own servers using
|
|
the Outgoing Webhooks API, but the Botserver is designed to make it
|
|
easy for a novice Python programmer to write a new bot and deploy it
|
|
in production.
|
|
|
|
### Installing the Zulip Botserver
|
|
|
|
Install the `zulip_botserver` PyPI package using `pip`:
|
|
```
|
|
pip install zulip_botserver
|
|
```
|
|
|
|
### Running bots using the Zulip Botserver
|
|
|
|
1. Register new bot users on the Zulip server's web interface.
|
|
|
|
* Log in to the Zulip server.
|
|
* Navigate to *Settings (<i class="fa fa-cog"></i>)* -> *Your bots* -> *Add a new bot*.
|
|
Select *Outgoing webhook* for bot type, fill out the form and click on *Create bot*.
|
|
* A new bot user should appear in the *Active bots* panel.
|
|
|
|
2. Download the `flaskbotrc` from the `your-bots` settings page. It
|
|
contains the configuration details for all the active outgoing
|
|
webhook bots. It's structure is very similar to that of .zuliprc.
|
|
|
|
3. Run the Zulip Botserver by passing the `flaskbotrc` to it. The
|
|
command format is:
|
|
|
|
```
|
|
zulip-bot-server --config-file <path_to_flaskbotrc> --hostname <address> --port <port>
|
|
```
|
|
|
|
If omitted, `hostname` defaults to `127.0.0.1` and `port` to `5002`.
|
|
|
|
4. Now set up the outgoing webhook service which will interact with
|
|
the server: Create an **Outgoing webhook** bot with its base url
|
|
of the form:
|
|
|
|
```
|
|
http://<hostname>:<port>/bots/<bot_name>
|
|
```
|
|
|
|
`bot_name` refers to the name in the email address you specified
|
|
for the bot. It can be obtained by removing `-bot@*.*` from the
|
|
bot email: For example, the bot name of a bot with an email
|
|
`followup-bot@zulip.com` is `followup`.
|
|
|
|
In the development environment, an outgoing webhook bot and
|
|
corresponding service already exist, with the email
|
|
`outgoing-webhook@zulip.com`. This can be used for interacting
|
|
with flask server bots.
|
|
|
|
5. Congrats, everything is set up! Test your botserver like you would
|
|
test a normal bot.
|
|
|
|
### Running Zulip Botserver with `supervisord`
|
|
|
|
[supervisord](http://supervisord.org/) is a popular tool for running
|
|
services in production. It helps ensure the service starts on boot,
|
|
manages log files, restarts the service if it crashes, etc. This
|
|
section documents how to run the Zulip Botserver using *supervisord*.
|
|
|
|
Running the Zulip Botserver with *supervisord* works almost like
|
|
running it manually.
|
|
|
|
0. Install *supervisord* via your package manager; e.g. on Debian/Ubuntu:
|
|
```
|
|
sudo apt-get install supervisor
|
|
```
|
|
|
|
1. Configure *supervisord*. *supervisord* stores its configuration in
|
|
`/etc/supervisor/conf.d`.
|
|
* Do **one** of the following:
|
|
* Download the [sample config file](
|
|
https://raw.githubusercontent.com/zulip/python-zulip-api/master/zulip_botserver/zulip-botserver-supervisord.conf)
|
|
and store it in `/etc/supervisor/conf.d/zulip-botserver.conf`.
|
|
* Copy the following section into your existing supervisord config file.
|
|
```
|
|
[program:zulip-bot-server]
|
|
command=zulip-bot-server --config-file=<path/to/your/flaskbotrc> --hostname <address> --port <port>
|
|
startsecs=3
|
|
stdout_logfile=/var/log/zulip-botserver.log ; all output of your botserver will be logged here
|
|
redirect_stderr=true
|
|
```
|
|
* Edit the `<>` sections according to your preferences.
|
|
|
|
2. Update *supervisord* to read the configuration file:
|
|
```
|
|
supervisorctl reread
|
|
supervisorctl update
|
|
```
|
|
(or you can use `/etc/init.d/supervisord restart`, but this is less
|
|
disruptive if you're using *supervisord* for other services as well).
|
|
|
|
3. Test if your setup is successful:
|
|
```
|
|
supervisorctl status
|
|
```
|
|
The output should include a line similar to this:
|
|
> zulip-bot-server RUNNING pid 28154, uptime 0:00:27
|
|
|
|
The standard output of the bot server will be logged to the path in
|
|
your *supervisord* configuration.
|
|
|
|
## Common problems
|
|
|
|
* My bot won't start
|
|
* Ensure that your API config file is correct (download the config file from the server).
|
|
* Ensure that you bot script is located in zulip_bots/bots/<my-bot>/
|
|
* Are you using your own Zulip development server? Ensure that you run your bot outside
|
|
the Vagrant environment.
|
|
* Some bots require Python 3. Try switching to a Python 3 environment before running
|
|
your bot.
|