Running interactive bots - Zulip

import {TabItem, Tabs} from "@astrojs/starlight/components";

import FlattenedSteps from "../../components/FlattenedSteps.astro"; import ZulipNote from "../../components/ZulipNote.astro";

Zulip's API has a powerful framework for interactive bots that react to messages in Zulip. You can write and run a custom bot, or run an existing Zulip bot.

Running a bot

<ZulipNote> Please be considerate when testing experimental bots on public servers such as chat.zulip.org. </ZulipNote>

You'll need:

An account in a Zulip organization (e.g., the Zulip development community, or a Zulip organization on your own development or production server).
A computer where you're running the bot from.

<Tabs> <TabItem label="Existing bot"> <FlattenedSteps> 1. [Create a bot](/help/add-a-bot-or-integration), making sure to select **Generic bot** as the **Bot type**.

  1. [Download the bot's `zuliprc` file](/api/api-keys#download-a-zuliprc-file).

  1. Use the following command to install the
     [`zulip_bots` Python package](https://pypi.org/project/zulip-bots/):

     ```
     pip3 install zulip_bots
     ```

  1. Use the following command to start the bot process *(replacing `<bot-name>`
     with the bot's name from the
     [Zulip bots directory](https://github.com/zulip/python-zulip-api/tree/main/zulip_bots/zulip_bots/bots)
     and `~/path/to/zuliprc` with the path to the `zuliprc` file you downloaded above)*:

     ```
     zulip-run-bot <bot-name> --config-file ~/path/to/zuliprc
     ```

  1. Check the output of the command above to make sure your bot is running.
     It should include the following line:

     ```
     INFO:root:starting message handling...
     ```

  1. Test your setup by [starting a new direct message](/help/starting-a-new-direct-message)
     with the bot or [mentioning](/help/mention-a-user-or-group) the bot on a channel.
</FlattenedSteps>

</TabItem> <TabItem label="Custom bot"> <FlattenedSteps> 1. [Write the code for your custom bot](/help/writing-bots), and note the path to the `<my-bot>.py` file you created.

  1. [Create a bot](/help/add-a-bot-or-integration), making sure to select
     **Generic bot** as the **Bot type**.

  1. [Download the bot's `zuliprc` file](/api/api-keys#download-a-zuliprc-file).

  1. Use the following command to install the
     [`zulip_bots` Python package](https://pypi.org/project/zulip-bots/):

     ```
     pip3 install zulip_bots
     ```

  1. Use the following command to start the bot process *(replacing
     `~/path/to/my_bot.py` with the path to your bot file and
     `~/path/to/zuliprc` with the path to the `zuliprc` file you downloaded above)*:

     ```
     zulip-run-bot ~/path/to/my_bot.py --config-file ~/path/to/zuliprc
     ```

     If your bot requires a third-party configuration file, you can specify
     it with the `--bot-config-file` option.

  1. Check the output of the command above to make sure your bot is running.
     It should include the following line:

     ```
     INFO:root:starting message handling...
     ```

  1. Test your setup by [starting a new direct message](/help/starting-a-new-direct-message)
     with the bot or [mentioning](/help/mention-a-user-or-group) the bot on a channel.
</FlattenedSteps>

</TabItem> </Tabs> <ZulipNote> To use the latest development version of the `zulip_bots` package, follow [these steps](/help/writing-bots#installing-a-development-version-of-the-zulip-bots-package). </ZulipNote>

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.