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 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.
pip install zulip_botsto install the package.
Hint: Do you want to install the latest development version? Check out this guide.
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
zuliprcconfiguration 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 explained here).
- The file will be downloaded to some place like
~/Downloads/zuliprc(depends on your browser and OS).
- Copy the file to a destination of your choice, e.g. to
Start the bot process.
zulip-run-bot <bot-name> --config-file ~/zuliprc-my-bot(using the path to the
zuliprcfile from step 3).
Check the output of the command. It should include the following line:
INFO:root:starting message handling...
Congrats! Your bot is running.
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 Zulip Botserver.
- 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 zulip_bots/bots/
- 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.