Skip to content

armgit / zulip

Public Imported from GitHub
0

Zulip server and web application. Open-source team chat that helps teams stay productive and focused.

4.3 KB
Raw Blame
---
title: Running interactive bots
---

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](/help/writing-bots), or run an
existing [Zulip bot](https://github.com/zulip/python-zulip-api/tree/main/zulip_bots/zulip_bots/bots).

## 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](https://zulip.com/development-community/),
  or a Zulip organization on your own
  [development](https://zulip.readthedocs.io/en/latest/development/overview.html) or
  [production](https://zulip.readthedocs.io/en/latest/production/install.html) 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](/help/deploying-bots) it on a
server using the Zulip Botserver.

## Related articles

* [Non-webhook integrations](/help/non-webhook-integrations)
* [Deploying bots](/help/deploying-bots)
* [Writing bots](/help/writing-bots)