Zulip's API has a powerful framework for interactive bots that react
to messages in Zulip. This page documents how to run a bot
implemented using that framework, both on your laptop for quick
testing as well in a production server environment.
On this page you'll find:
- A step-by-step tutorial on how to run a bot.
- Common problems when developing/running bots and their solutions.
Installing the Zulip bots package
Running a bot
This guide will show you how to run an existing Zulip bot
- An account in an organization on a Zulip server
(e.g. chat.zulip.org or
yourSubdomain.zulipchat.com, or your own development server).
Within that Zulip organization, users will be able to interact with
- 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.
pip install zulip_bots to install the package.
Hint: Do you want to install the latest development version? Check
Register a new bot user on the Zulip server's web interface.
- Log in to the Zulip server.
- Navigate to Settings () -> 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.
Download the bot's
zuliprc configuration file to your computer.
- Go to Settings -> Your bots.
- In the Active bots panel, click on the little green download icon
to download its configuration file zuliprc (the structure of this file is
- The file will be downloaded to some place like
on your browser and OS).
- Copy the file to a destination of your choice, e.g. to
Start the bot process.
To talk with the bot, mention its name
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
environment where it'll stay up, by deploying it on a server using the
- My bot won't start
- Ensure that your API config file is correct (download the config file from the server).
- Ensure that your bot script is located in
- 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