134 lines
4.4 KiB
Markdown
134 lines
4.4 KiB
Markdown
# Overview
|
|
|
|
This is the documentation for an experimental new system for writing
|
|
bots that react to messages.
|
|
|
|
This directory contains library code for running Zulip
|
|
bots that react to messages sent by users.
|
|
|
|
This document explains how to run the code, and it also
|
|
talks about the architecture for creating bots.
|
|
|
|
## Design goals
|
|
|
|
The goal is to have a common framework for hosting a bot that reacts
|
|
to messages in any of the following settings:
|
|
|
|
* Run as a long-running process using `call_on_each_event`
|
|
(implemented today).
|
|
|
|
* Run via a simple web service that can be deployed to PAAS providers
|
|
and handles outgoing webhook requests from Zulip.
|
|
|
|
* Embedded into the Zulip server (so that no hosting is required),
|
|
which would be done for high quality, reusable bots; we would have a
|
|
nice "bot store" sort of UI for browsing and activating them.
|
|
|
|
## Running bots
|
|
|
|
Here is an example of running the "follow-up" bot from
|
|
inside a Zulip repo:
|
|
|
|
cd ~/zulip/contrib_bots
|
|
./run.py lib/followup.py --config-file ~/.zuliprc-prod
|
|
|
|
Once the bot code starts running, you will see a
|
|
message explaining how to use the bot, as well as
|
|
some log messages. You can use the `--quiet` option
|
|
to suppress these messages.
|
|
|
|
The bot code will run continuously until you kill them with
|
|
control-C (or otherwise).
|
|
|
|
### Zulip Configuration
|
|
|
|
For this document we assume you have some prior experience
|
|
with using the Zulip API, but here is a quick review of
|
|
what a `.zuliprc` files looks like. You can connect to the
|
|
API as your own human user, or you can go into the Zulip settings
|
|
page to create a user-owned bot.
|
|
|
|
[api]
|
|
email=someuser@example.com
|
|
key=<your api key>
|
|
site=https://zulip.somewhere.com
|
|
|
|
|
|
### Third Party Configuration
|
|
|
|
If your bot interacts with a non-Zulip service, you may
|
|
have to configure keys or usernames or URLs or similar
|
|
information to hit the other service.
|
|
|
|
Do **not** put third party configuration information in your
|
|
`.zuliprc` file. Do not put third party configuration
|
|
information anywhere in your Zulip directory. Instead,
|
|
create a separate configuration file for the third party's
|
|
configuration in your home directory.
|
|
|
|
### Python dependencies
|
|
|
|
If your module requires Python modules that are not either
|
|
part of the standard Python library or the Zulip API
|
|
distribution, we ask that you put a comment at the top
|
|
of your bot explaining how to install the dependencies.
|
|
|
|
Right now we don't support any kind of automatic build
|
|
environment for bots, so it's currently up to the users
|
|
of the bots to manage their dependencies. This may change
|
|
in the future.
|
|
|
|
## Architecture
|
|
|
|
In order to make bot development easy, we separate
|
|
out boilerplate code (loading up the Client API, etc.)
|
|
from bot-specific code (do what makes the bot unique).
|
|
|
|
All of the boilerplate code lives in `../run.py`. The
|
|
runner code does things like find where it can import
|
|
the Zulip API, instantiate a client with correct
|
|
credentials, set up the logging level, find the
|
|
library code for the specific bot, etc.
|
|
|
|
Then, for bot-specific logic, you will find `.py` files
|
|
in the `lib` directory (i.e. the same directory as the
|
|
document you are reading now).
|
|
|
|
Each bot library simply needs to do the following:
|
|
|
|
- Define a class that supports the methods `usage`,
|
|
`triage_message`, and `handle_message`.
|
|
- Set `handler_class` to be the name of that class.
|
|
|
|
(We make this a two-step process, so that you can give
|
|
a descriptive name to your handler class.)
|
|
|
|
## Portability
|
|
|
|
Creating a handler class for each bot allows your bot
|
|
code to be more portable. For example, if you want to
|
|
use your bot code in some other kind of bot platform, then
|
|
if all of your bots conform to the `handler_class` protocol,
|
|
you can write simple adapter code to use them elsewhere.
|
|
|
|
Another future direction to consider is that Zulip will
|
|
eventually support running certain types of bots on
|
|
the server side, to essentially implement post-send
|
|
hooks and things of those nature.
|
|
|
|
Conforming to the `handler_class` protocol will make
|
|
it easier for Zulip admins to integrate custom bots.
|
|
|
|
In particular, `run.py` already passes in instances
|
|
of a restricted variant of the Client class to your
|
|
library code, which helps you ensure that your bot
|
|
does only things that would be acceptable for running
|
|
in a server-side environment.
|
|
|
|
## Other approaches
|
|
|
|
If you are not interested in running your bots on the
|
|
server, then you can still use the full Zulip API. The
|
|
hope, though, is that this architecture will make
|
|
writing simple bots a quick/easy process.
|