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: Writing interactive bots
---

import {Steps} 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. This page will guide you through writing your own interactive bot.

* [Installing a development version of the Zulip bots package](#installing-a-development-version-of-the-zulip-bots-package)
* [Bot template](#bot-template)
* [Testing a bot's output](#testing-a-bots-output)
* [Troubleshooting](#troubleshooting)

## Installing a development version of the Zulip bots package

This will provide convenient tooling for developing and testing your bot.

<FlattenedSteps>
  1. Clone the [python-zulip-api](https://github.com/zulip/python-zulip-api)
     repository:

     ```
     git clone https://github.com/zulip/python-zulip-api.git
     ```

  1. Navigate into your cloned repository:

     ```
     cd python-zulip-api
     ```

  1. Install all requirements in a Python virtualenv:

     ```
     python3 ./tools/provision
     ```

  1. Run the command provided in the final output of the `provision` process to
     enter the new virtualenv. The command will be of the form `source .../activate`.

  1. You should now see the name of your virtualenv preceding your prompt (e.g.,
     `(zulip-api-py3-venv)`).
</FlattenedSteps>

<ZulipNote>
  `provision` installs the `zulip`, `zulip_bots`, and
  `zulip_botserver` packages in developer mode. This enables you to
  modify these packages and then run your modified code without
  having to first re-install the packages or re-provision.
</ZulipNote>

## Bot template

The only file required for a new bot is `<my-bot>.py`. It has the following
structure:

```python
class MyBotHandler(object):
    '''
    A docstring documenting this bot.
    '''

    def usage(self):
        return '''Your description of the bot'''

    def handle_message(self, message, bot_handler):
        # add your code here

handler_class = MyBotHandler
```

The class name (in this case *MyBotHandler*) can be defined by you
and should match the name of your bot. To register your bot's class,
adjust the last line `handler_class = MyBotHandler` to match your
class name.

Every bot must implement the `usage(self)` and `handle_message(self, message,
bot_handler)` functions. They are described in detail in the
[interactive bots API documentation](/help/interactive-bots-api).

All the files associated with a bot (e.g., tests, documentation, etc.) should be
placed in the same directory as `<my-bot>.py`.

## Testing a bot's output

You can see how a bot reacts to a message without setting it up on a server,
using the `zulip-bot-shell` tool.

<Steps>
  1. [Install all requirements](#installing-a-development-version-of-the-zulip-bots-package).
  1. Run `zulip-bot-shell` to test one of the bots in
     [`zulip_bots/bots`](https://github.com/zulip/python-zulip-api/tree/main/zulip_bots/zulip_bots/bots).
</Steps>

Example invocations:

```
> zulip-bot-shell converter

Enter your message: "12 meter yard"
Response: 12.0 meter = 13.12336 yard

> zulip-bot-shell -b ~/followup.conf followup

Enter your message: "Task completed"
Response: stream: followup topic: [email protected]
          from [email protected]: Task completed

```

Note that the `-b` (aka `--bot-config-file`) argument is for an optional third party
config file (e.g., \~/giphy.conf), which only applies to certain types of bots.

## Troubleshooting

### I modified my bot's code, yet the changes don't seem to have an effect

Ensure that you restarted the `zulip-run-bot` script.

### My bot won't start

* Ensure that your API config file is correct (download the config file from the server).
* Ensure that you 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.

## Related articles

* [Interactive bots API](/help/interactive-bots-api)
* [Writing tests for bots](/help/writing-tests-for-interactive-bots)
* [Running bots](/help/running-bots)
* [Deploying bots](/help/deploying-bots)
* [Configuring the Python bindings](/api/configuring-python-bindings)
* [Non-webhook integrations](/help/non-webhook-integrations)