Zulip server and web application. Open-source team chat that helps teams stay productive and focused.
---
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)