2017-10-04 21:11:27 +02:00
|
|
|
# Interactive bots
|
2017-10-02 13:19:41 +02:00
|
|
|
|
2017-10-04 21:11:27 +02:00
|
|
|
Zulip's API has a powerful framework for interactive bots that react
|
2018-10-20 22:10:00 +02:00
|
|
|
to messages in Zulip.
|
2017-10-02 13:19:41 +02:00
|
|
|
|
2017-10-04 18:01:31 +02:00
|
|
|
## Running a bot
|
2017-10-02 13:19:41 +02:00
|
|
|
|
2018-10-20 22:10:00 +02:00
|
|
|
This guide will show you how to run an existing Zulip bot
|
|
|
|
|
found in [zulip_bots/bots](
|
2021-08-31 23:32:37 +02:00
|
|
|
https://github.com/zulip/python-zulip-api/tree/main/zulip_bots/zulip_bots/bots).
|
2017-10-02 13:19:41 +02:00
|
|
|
|
2018-10-20 22:10:00 +02:00
|
|
|
You'll need:
|
2017-10-02 13:19:41 +02:00
|
|
|
|
2018-10-20 22:10:00 +02:00
|
|
|
* An account in a Zulip organization
|
2021-07-26 07:11:56 +02:00
|
|
|
(e.g. [chat.zulip.org](/developer-community/),
|
2018-10-20 22:10:00 +02:00
|
|
|
`<yourSubdomain>.zulipchat.com`, or a Zulip organization on your own
|
|
|
|
|
[development](https://zulip.readthedocs.io/en/latest/development/overview.html) or
|
|
|
|
|
[production](https://zulip.readthedocs.io/en/latest/production/install.html) server).
|
2017-10-02 13:19:41 +02:00
|
|
|
* A computer where you're running the bot from.
|
|
|
|
|
|
2017-12-14 22:00:15 +01:00
|
|
|
**Note: Please be considerate when testing experimental bots on public servers such as chat.zulip.org.**
|
2017-10-02 13:19:41 +02:00
|
|
|
|
2018-10-20 22:10:00 +02:00
|
|
|
1. Go to your Zulip account and
|
|
|
|
|
[add a bot](/help/add-a-bot-or-integration). Use **Generic bot** as the bot type.
|
2017-10-02 13:19:41 +02:00
|
|
|
|
2018-05-14 02:43:32 +02:00
|
|
|
1. Download the bot's `zuliprc` configuration file to your computer.
|
2017-10-02 13:19:41 +02:00
|
|
|
|
2019-08-24 00:50:22 +02:00
|
|
|
1. Download the `zulip_bots` Python package to your computer using `pip3 install zulip_bots`.
|
2018-10-20 22:10:00 +02:00
|
|
|
|
|
|
|
|
*Note: Click
|
|
|
|
|
[here](
|
|
|
|
|
writing-bots#installing-a-development-version-of-the-zulip-bots-package)
|
|
|
|
|
to install the latest development version of the package.*
|
2017-10-02 13:19:41 +02:00
|
|
|
|
2018-10-20 22:10:00 +02:00
|
|
|
1. Start the bot process on your computer.
|
2017-10-02 13:19:41 +02:00
|
|
|
|
|
|
|
|
* Run
|
|
|
|
|
```
|
2018-10-20 22:10:00 +02:00
|
|
|
zulip-run-bot <bot-name> --config-file ~/path/to/zuliprc
|
2017-10-02 13:19:41 +02:00
|
|
|
```
|
2018-10-20 22:10:00 +02:00
|
|
|
|
|
|
|
|
(replacing `~/path/to/zuliprc` with the path to the `zuliprc` file you downloaded above).
|
|
|
|
|
|
2018-05-14 03:37:52 +02:00
|
|
|
* Check the output of the command. It should include the following line:
|
2017-10-02 13:19:41 +02:00
|
|
|
|
2017-12-14 22:00:15 +01:00
|
|
|
INFO:root:starting message handling...
|
2017-10-02 13:19:41 +02:00
|
|
|
|
2018-05-14 03:37:52 +02:00
|
|
|
Congrats! Your bot is running.
|
|
|
|
|
|
2018-10-20 22:10:00 +02:00
|
|
|
1. To talk with the bot, at-mention its name, like `@**bot-name**`.
|
2017-10-02 13:19:41 +02:00
|
|
|
|
2017-10-04 21:11:27 +02:00
|
|
|
You can now play around with the bot and get it configured the way you
|
|
|
|
|
like. Eventually, you'll probably want to run it in a production
|
2018-10-20 22:10:00 +02:00
|
|
|
environment where it'll stay up, by [deploying](/api/deploying-bots) it on a server using the
|
2017-10-04 21:11:27 +02:00
|
|
|
Zulip Botserver.
|
2017-10-02 13:19:41 +02:00
|
|
|
|
|
|
|
|
## Common problems
|
|
|
|
|
|
|
|
|
|
* My bot won't start
|
|
|
|
|
* Ensure that your API config file is correct (download the config file from the server).
|
2018-07-06 23:26:34 +02:00
|
|
|
* Ensure that your bot script is located in `zulip_bots/bots/<my-bot>/`
|
2017-10-02 13:19:41 +02:00
|
|
|
* 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.
|
