CodeCow/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2026-06-03 21:01:43 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

help: Move writing-bots from API docs to help center.

Browse Source
This commit is contained in:
Lauryn Menard 2026-01-09 17:17:30 +01:00 committed by Tim Abbott
parent d57f38de20
commit c8e2182dfc
13 changed files with 61 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
api_docs/configuring-python-bindings.md
View File

@ -3,7 +3,7 @@
Zulip provides a set of tools that allows interacting with its API more
easily, called the [Python bindings](https://pypi.python.org/pypi/zulip/).
One of the most notable use cases for these bindings are bots developed
using Zulip's [bot framework](/api/writing-bots).
using Zulip's [bot framework](/help/writing-bots).
In order to use them, you need to configure them with your identity
(account, API key, and Zulip server URL). There are a few ways to

4
api_docs/non-webhook-integrations.md
View File

@ -20,7 +20,7 @@ them. Zulip supports several other types of integrations.
documentation for the third party software in order to learn how to
write the integration.
* **Interactive bots**. See [Writing bots](/api/writing-bots).
* **Interactive bots**. See [Writing bots](/help/writing-bots).
A few notes on how to do these:
@ -55,7 +55,7 @@ examples of ideal UAs are:
* [Running bots](/help/running-bots)
* [Deploying bots](/help/deploying-bots)
* [Writing bots](/api/writing-bots)
* [Writing bots](/help/writing-bots)
[incoming-webhooks-overview]: https://zulip.readthedocs.io/en/latest/webhooks/incoming-webhooks-overview.html
[webhooks-general-advice]: https://zulip.readthedocs.io/en/latest/webhooks/incoming-webhooks-overview.html#general-advice

2
api_docs/sidebar_index.md
View File

@ -7,7 +7,7 @@
## Interactive bots
* [Writing bots](/api/writing-bots)
* [Writing bots](/help/writing-bots)
* [Interactive bots API](/help/interactive-bots-api)
* [Writing tests for bots](/help/writing-tests-for-interactive-bots)
* [Running bots](/help/running-bots)

1
starlight_help/astro.config.mjs
View File

@ -667,6 +667,7 @@ export default defineConfig({
},
"view-your-bots",
"view-all-bots-in-your-organization",
"writing-bots",
"interactive-bots-api",
"writing-tests-for-interactive-bots",
"running-bots",

2
starlight_help/src/content/docs/deploying-bots.mdx
View File

@ -250,4 +250,4 @@ Botserver with SSL using an `nginx` or `Apache` reverse proxy and
* [Non-webhook integrations](/api/non-webhook-integrations)
* [Running bots](/help/running-bots)
* [Writing bots](/api/writing-bots)
* [Writing bots](/help/writing-bots)

2
starlight_help/src/content/docs/interactive-bots-api.mdx
View File

@ -300,5 +300,5 @@ with use_storage(bot_handler.storage, ["foo", "bar"]) as cache:
## Related articles
* [Writing bots](/api/writing-bots)
* [Writing bots](/help/writing-bots)
* [Writing tests for bots](/help/writing-tests-for-interactive-bots)

2
starlight_help/src/content/docs/moving-from-discord.mdx
View File

@ -65,7 +65,7 @@ think through the transition process in your own context.
[topics](/help/introduction-to-topics) give each conversation its own
space, so you likely need fewer channels than in Discord.
1. To recreate your Discord bots in Zulip, check out Zulip's [native
integrations](/integrations), and the [guide](/api/writing-bots) on writing
integrations](/integrations), and the [guide](/help/writing-bots) on writing
your own interactive bots.
</Steps>

6
starlight_help/src/content/docs/running-bots.mdx
View File

@ -6,7 +6,7 @@ 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 your own interactive bot](/api/writing-bots), or run an
in Zulip. You can [write your own interactive 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
@ -60,7 +60,7 @@ You'll need:
<ZulipNote>
To use the latest development version of the `zulip_bots` package, follow
[these steps](writing-bots#installing-a-development-version-of-the-zulip-bots-package).
[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
@ -72,4 +72,4 @@ server using the Zulip Botserver.
* [Non-webhook integrations](/api/non-webhook-integrations)
* [Deploying bots](/help/deploying-bots)
* [Writing bots](/api/writing-bots)
* [Writing bots](/help/writing-bots)

87
api_docs/writing-bots.md → starlight_help/src/content/docs/writing-bots.mdx
View File

@ -1,52 +1,57 @@
# Writing interactive bots
---
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](#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.
{start_tabs}
<FlattenedSteps>
1. Clone the [python-zulip-api](https://github.com/zulip/python-zulip-api)
repository:
1. Clone the [python-zulip-api](https://github.com/zulip/python-zulip-api)
repository:
```
git clone https://github.com/zulip/python-zulip-api.git
```
```
git clone https://github.com/zulip/python-zulip-api.git
```
1. Navigate into your cloned repository:
1. Navigate into your cloned repository:
```
cd python-zulip-api
```
```
cd python-zulip-api
```
1. Install all requirements in a Python virtualenv:
1. Install all requirements in a Python virtualenv:
```
python3 ./tools/provision
```
```
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. 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>
1. You should now see the name of your virtualenv preceding your prompt (e.g.,
`(zulip-api-py3-venv)`).
!!! tip ""
`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.
{end_tabs}
<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
@ -85,13 +90,11 @@ placed in the same directory as `<my-bot>.py`.
You can see how a bot reacts to a message without setting it up on a server,
using the `zulip-bot-shell` tool.
{start_tabs}
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).
{end_tabs}
<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:
@ -110,15 +113,15 @@ Response: stream: followup topic: foo_sender@zulip.com
```
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.
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.
### 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.
### 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>/`

2
starlight_help/src/content/docs/writing-tests-for-interactive-bots.mdx
View File

@ -124,5 +124,5 @@ to see examples of bot tests.
## Related articles
* [Writing bots](/api/writing-bots)
* [Writing bots](/help/writing-bots)
* [Interactive bots API](/help/interactive-bots-api)

2
templates/corporate/zulip-cloud.html
View File

@ -71,7 +71,7 @@
<p>
Connect Zulip to other tools with <a href="/integrations/">native
integrations</a> and powerful <a href="/api/">APIs</a>. An easy-to-use <a
href="https://zulip.com/api/writing-bots">bot
href="/help/writing-bots">bot
framework</a>
lets you <a
href="/case-studies/windborne/#the-perfect-platform-for-llm-bots">bring

4
templates/zerver/integrations/catalog.html
View File

@ -66,7 +66,7 @@
<a href="https://zulip.readthedocs.io/en/latest/webhooks/incoming-webhooks-overview.html">
<h4>{% trans %}Incoming webhooks{% endtrans %}</h4>
</a>
<a href="/api/writing-bots">
<a href="/help/writing-bots">
<h4>{% trans %}Interactive bots{% endtrans %}</h4>
</a>
<a href="/api/rest">
@ -93,7 +93,7 @@
<a href="https://zulip.readthedocs.io/en/latest/webhooks/incoming-webhooks-overview.html">
<h4>{% trans %}Incoming webhooks{% endtrans %}</h4>
</a>
<a href="/api/writing-bots">
<a href="/help/writing-bots">
<h4>{% trans %}Interactive bots{% endtrans %}</h4>
</a>
<a href="/api/rest">

1
zerver/lib/url_redirects.py
View File

@ -18,6 +18,7 @@ REDIRECTED_TO_HELP_DOCUMENTATION: list[URLRedirect] = [
"/api/writing-tests-for-interactive-bots", "/help/writing-tests-for-interactive-bots"
),
URLRedirect("/api/interactive-bots-api", "/help/interactive-bots-api"),
URLRedirect("/api/writing-bots", "/help/writing-bots"),
]
API_DOCUMENTATION_REDIRECTS: list[URLRedirect] = [