Users

Real-time events

Deploying bots in production

Usually, work on a bot starts on a laptop. At some point, you'll want
to deploy your bot in a production environment, so that it'll stay up
regardless of what's happening with your laptop. There are several
options for doing so:

The simplest is running zulip-run-bot inside a screen session on
a server. This works, but if your server reboots, you'll need to
manually restart it, so we don't recommend it.

Using supervisord or a similar tool for managing a production
process with zulip-run-bot. This consumes a bit of resources
(since you need a persistent process running), but otherwise works
great.

Using the Zulip Botserver, which is a simple Flask server for
running a bot in production, and connecting that to Zulip's outgoing
webhooks feature. This can be deployed in environments like
Heroko's free tier without running a persistent process.

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 a bot using the Zulip Botserver

Construct the URL for your bot, which will be of the form:

http://<hostname>:<port>

where the hostname is the hostname you'll be running the bot
server on, and port is the port for it (the recommended default
is 5002).

Register new bot users on the Zulip server's web interface.

Log in to the Zulip server.

Navigate to Settings () -> Your bots -> Add a new bot.
Select Outgoing webhook for bot type, fill out the form (using
the URL from above) and click on Create bot.

A new bot user should appear in the Active bots panel.

Download the zuliprc file for your bot from the Active Bots
panel, using the download button.

Run the Botserver, where helloworld is the name of the bot you
want to run:

zulip-botserver --config-file <path_to_zuliprc> --bot-name=helloworld

You can specify the port number and various other options; run
zulip-botserver --help to see how to do this.

Congrats, everything is set up! Test your Botserver like you would
test a normal bot.

Running multiple bots using the Zulip Botserver

The Zulip Botserver also supports running multiple bots from a single
Botserver process. You can do this with the following procedure.

Download the botserverrc from the your-bots settings page, using
the "Download config of all active outgoing webhook bots in Zulip
Botserver format." option at the top.

Open the botserverrc. It should contain one or more sections that look like this:

Each section contains the configuration for an outgoing webhook bot. For each
bot, enter the name of the bot you want to run in the square brackets [].
For example, if we want foo-bot@hostname to run the helloworld bot, our
new section would look like this:

Each section contains the configuration for an outgoing webhook bot. For each
bot, enter the name of the bot you want to run in the square brackets [].
For example, if we want foo-bot@hostname to run the helloworld bot, our
new section would look like this:

Run the Zulip Botserver by passing the botserverrc to it. The
command format is:

zulip-botserver --config-file <path_to_botserverrc>

If omitted, hostname defaults to 127.0.0.1 and port to 5002.

Running Zulip Botserver with supervisord

supervisord 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.