Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
zulip/templates/zerver/api/running-bots.md

3.2 KiB
Raw Blame History

Interactive bots

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 found in zulip_bots/bots.

You need:

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

  1. Run pip install zulip_bots to install the package.

    Hint: Do you want to install the latest development version? Check out this guide.

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

  3. 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 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 ~/zuliprc-my-bot.

  4. Start the bot process.

    • Run

      zulip-run-bot <bot-name> --config-file ~/zuliprc-my-bot

      (using the path to the zuliprc file 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.

  5. To talk with the bot, mention its name @**bot-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.

Common problems

  • 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/<my-bot>/
    • 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.