diff --git a/api_docs/api-keys.md b/api_docs/api-keys.md
index bc0b3ee958..6fb98e2af9 100644
--- a/api_docs/api-keys.md
+++ b/api_docs/api-keys.md
@@ -2,9 +2,9 @@
An **API key** is how a bot identifies itself to Zulip. For the official
clients, such as the Python bindings, we recommend [downloading a `zuliprc`
-file](/api/configuring-python-bindings#download-a-zuliprc-file).
-This file contains an API key along with other necessary configuration values
-for using the Zulip API with a specific account on a Zulip server.
+file](/api/configuring-python-bindings#download-a-zuliprc-file). This file
+contains an API key and other necessary configuration values for using the
+Zulip API with a specific account on a Zulip server.
## Get a bot's API key
diff --git a/api_docs/deploying-bots.md b/api_docs/deploying-bots.md
index 31185f9a7b..6aff1f085c 100644
--- a/api_docs/deploying-bots.md
+++ b/api_docs/deploying-bots.md
@@ -44,7 +44,7 @@ Botserver interaction are:
1. The Zulip server sends a POST request to the Botserver on `https://bot-server.example.com/`:
- ```json
+ ```
{
"message":{
"content":"@**My Bot User** hello world",
@@ -57,9 +57,8 @@ Botserver interaction are:
This URL is configured in the Zulip web-app in your Bot User's settings.
-1. The Botserver searches for a bot to handle the message.
-
-1. The Botserver executes your bot's `handle_message` code.
+1. The Botserver searches for a bot to handle the message, and executes your
+ bot's `handle_message` code.
Your bot's code should work just like it does with `zulip-run-bot`;
for example, you reply using
@@ -75,6 +74,7 @@ pip3 install zulip_botserver
### Running a bot using the Zulip Botserver
+{start_tabs}
1. Construct the URL for your bot, which will be of the form:
@@ -108,11 +108,15 @@ pip3 install zulip_botserver
1. Congrats, everything is set up! Test your Botserver like you would
test a normal bot.
+{end_tabs}
+
### Running multiple bots using the Zulip Botserver
The Zulip Botserver also supports running multiple bots from a single
Botserver process. You can do this with the following procedure.
+{start_tabs}
+
1. Download the `botserverrc` from the `your-bots` settings page, using
the "Download config of all active outgoing webhook bots in Zulip
Botserver format." option at the top.
@@ -160,6 +164,8 @@ Botserver process. You can do this with the following procedure.
If omitted, `hostname` defaults to `127.0.0.1` and `port` to `5002`.
+{end_tabs}
+
### Running Zulip Botserver with supervisord
[supervisord](http://supervisord.org/) is a popular tool for running
@@ -170,6 +176,8 @@ section documents how to run the Zulip Botserver using *supervisord*.
Running the Zulip Botserver with *supervisord* works almost like
running it manually.
+{start_tabs}
+
1. Install *supervisord* via your package manager; e.g. on Debian/Ubuntu:
```
@@ -216,6 +224,8 @@ running it manually.
The standard output of the Botserver will be logged to the path in
your *supervisord* configuration.
+{end_tabs}
+
If you are hosting the Botserver yourself (as opposed to using a
hosting service that provides SSL), we recommend securing your
Botserver with SSL using an `nginx` or `Apache` reverse proxy and
@@ -223,18 +233,17 @@ Botserver with SSL using an `nginx` or `Apache` reverse proxy and
### Troubleshooting
-1. Make sure the API key you're using is for an [outgoing webhook
- bot](/api/outgoing-webhooks) and you've
- correctly configured the URL for your Botserver.
+- Make sure the API key you're using is for an [outgoing webhook
+ bot](/api/outgoing-webhooks) and you've
+ correctly configured the URL for your Botserver.
-1. Your Botserver needs to be accessible from your Zulip server over
- HTTP(S). Make sure any firewall allows the connection. We
- recommend using [zulip-run-bot](running-bots) instead for
- development/testing on a laptop or other non-server system.
-
- If your Zulip server is self-hosted, you can test by running `curl
- http://zulipbotserver.example.com:5002` from your Zulip server;
- the output should be:
+- Your Botserver needs to be accessible from your Zulip server over
+ HTTP(S). Make sure any firewall allows the connection. We
+ recommend using [zulip-run-bot](running-bots) instead for
+ development/testing on a laptop or other non-server system.
+ If your Zulip server is self-hosted, you can test by running `curl
+ http://zulipbotserver.example.com:5002` from your Zulip server;
+ the output should be:
```
$ curl http://zulipbotserver.example.com:5002/
@@ -243,3 +252,9 @@ Botserver with SSL using an `nginx` or `Apache` reverse proxy and
Method Not Allowed
The method is not allowed for the requested URL.
```
+
+## Related articles
+
+* [Non-webhook integrations](/api/non-webhook-integrations)
+* [Running bots](/api/running-bots)
+* [Writing bots](/api/writing-bots)
diff --git a/api_docs/incoming-webhooks-overview.md b/api_docs/incoming-webhooks-overview.md
index 041e189ed7..52890f7606 100644
--- a/api_docs/incoming-webhooks-overview.md
+++ b/api_docs/incoming-webhooks-overview.md
@@ -197,3 +197,9 @@ Parameters accepted in the URL include:
[browse-streams]: /help/browse-and-subscribe-to-streams
[add-bot]: /help/add-a-bot-or-integration
[url-encoder]: https://www.urlencoder.org/
+
+## Related articles
+
+* [Integrations overview](/api/integrations-overview)
+* [Incoming webhook walkthrough](/api/incoming-webhooks-walkthrough)
+* [Non-webhook integrations](/api/non-webhook-integrations)
diff --git a/api_docs/incoming-webhooks-walkthrough.md b/api_docs/incoming-webhooks-walkthrough.md
index 32ba6ebdc0..64d11a1ce7 100644
--- a/api_docs/incoming-webhooks-walkthrough.md
+++ b/api_docs/incoming-webhooks-walkthrough.md
@@ -289,15 +289,19 @@ the [management commands][management-commands] documentation.
### Integrations Dev Panel
This is the GUI tool.
+{start_tabs}
+
1. Run `./tools/run-dev` then go to http://localhost:9991/devtools/integrations/.
-2. Set the following mandatory fields:
+1. Set the following mandatory fields:
**Bot** - Any incoming webhook bot.
**Integration** - One of the integrations.
**Fixture** - Though not mandatory, it's recommended that you select one and then tweak it if necessary.
The remaining fields are optional, and the URL will automatically be generated.
-3. Click **Send**!
+1. Click **Send**!
+
+{end_tabs}
By opening Zulip in one tab and then this tool in another, you can quickly tweak
your code and send sample messages for many different test fixtures.
@@ -480,24 +484,21 @@ screenshot. Mostly you should plan on templating off an existing guide, like
## Step 7: Preparing a pull request to zulip/zulip
-When you have finished your webhook integration and are ready for it to be
-available in the Zulip product, follow these steps to prepare your pull
-request:
+When you have finished your webhook integration, follow these guidelines before
+pushing the code to your fork and submitting a pull request to zulip/zulip:
-1. Run tests including linters and ensure you have addressed any issues they
- report. See [Testing](https://zulip.readthedocs.io/en/latest/testing/testing.html)
- and [Linters](https://zulip.readthedocs.io/en/latest/testing/linters.html) for details.
-2. Read through [Code styles and conventions](
- https://zulip.readthedocs.io/en/latest/contributing/code-style.html) and take a look
- through your code to double-check that you've followed Zulip's guidelines.
-3. Take a look at your Git history to ensure your commits have been clear and
- logical (see [Commit discipline](
- https://zulip.readthedocs.io/en/latest/contributing/commit-discipline.html) for tips). If not,
- consider revising them with `git rebase --interactive`. For most incoming webhooks,
- you'll want to squash your changes into a single commit and include a good,
- clear commit message.
-4. Push code to your fork.
-5. Submit a pull request to zulip/zulip.
+- Run tests including linters and ensure you have addressed any issues they
+ report. See [Testing](https://zulip.readthedocs.io/en/latest/testing/testing.html)
+ and [Linters](https://zulip.readthedocs.io/en/latest/testing/linters.html) for details.
+- Read through [Code styles and conventions](
+ https://zulip.readthedocs.io/en/latest/contributing/code-style.html) and take a look
+ through your code to double-check that you've followed Zulip's guidelines.
+- Take a look at your Git history to ensure your commits have been clear and
+ logical (see [Commit discipline](
+ https://zulip.readthedocs.io/en/latest/contributing/commit-discipline.html) for tips). If not,
+ consider revising them with `git rebase --interactive`. For most incoming webhooks,
+ you'll want to squash your changes into a single commit and include a good,
+ clear commit message.
If you would like feedback on your integration as you go, feel free to post a
message on the [public Zulip instance](https://chat.zulip.org/#narrow/stream/integrations).
@@ -652,3 +653,8 @@ with a string describing the unsupported event type, like so:
```
raise UnsupportedWebhookEventTypeError(event_type)
```
+
+## Related articles
+
+* [Integrations overview](/api/integrations-overview)
+* [Incoming webhook integrations](/api/incoming-webhooks-overview)
diff --git a/api_docs/installation-instructions.md b/api_docs/installation-instructions.md
index 216ca9238e..544618a5a5 100644
--- a/api_docs/installation-instructions.md
+++ b/api_docs/installation-instructions.md
@@ -40,3 +40,7 @@ No download required!
See also [user-contributed client libraries](/api/client-libraries)
for many other languages.
+
+## Related articles
+
+* [Configuring the Python bindings](/api/configuring-python-bindings)
diff --git a/api_docs/non-webhook-integrations.md b/api_docs/non-webhook-integrations.md
index 560b961ea2..5ec42e3fc6 100644
--- a/api_docs/non-webhook-integrations.md
+++ b/api_docs/non-webhook-integrations.md
@@ -4,14 +4,14 @@
fastest to write, but sometimes a third-party product just doesn't support
them. Zulip supports several other types of integrations.
-1. **Python script integrations**
+* **Python script integrations**
(examples: SVN, Git), where we can get the service to call our integration
(by shelling out or otherwise), passing in the required data. Our preferred
model for these is to ship these integrations in the
[Zulip Python API distribution](https://github.com/zulip/python-zulip-api/tree/main/zulip),
within the `integrations` directory there.
-1. **Plugin integrations** (examples:
+* **Plugin integrations** (examples:
Jenkins, Hubot, Trac) where the user needs to install a plugin into their
existing software. These are often more work, but for some products are the
only way to integrate with the product at all.
@@ -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.
-1. **Interactive bots**. See [Writing bots](/api/writing-bots).
+* **Interactive bots**. See [Writing bots](/api/writing-bots).
A few notes on how to do these:
@@ -51,3 +51,9 @@ examples of ideal UAs are:
* The [general advice](/api/incoming-webhooks-overview#general-advice) for
webhook integrations applies here as well.
+
+## Related articles
+
+* [Running bots](/api/running-bots)
+* [Deploying bots](/api/deploying-bots)
+* [Writing bots](/api/writing-bots)
diff --git a/api_docs/outgoing-webhooks.md b/api_docs/outgoing-webhooks.md
index d802057fbc..55aaf29382 100644
--- a/api_docs/outgoing-webhooks.md
+++ b/api_docs/outgoing-webhooks.md
@@ -29,9 +29,9 @@ To register an outgoing webhook:
There are currently two ways to trigger an outgoing webhook:
-1. **@-mention** the bot user in a stream. If the bot replies, its
+* **@-mention** the bot user in a stream. If the bot replies, its
reply will be sent to that stream and topic.
-2. **Send a direct message** with the bot as one of the recipients.
+* **Send a direct message** with the bot as one of the recipients.
If the bot replies, its reply will be sent to that thread.
## Timeouts
diff --git a/api_docs/running-bots.md b/api_docs/running-bots.md
index fb77f307cb..f54f3286cf 100644
--- a/api_docs/running-bots.md
+++ b/api_docs/running-bots.md
@@ -20,39 +20,42 @@ You'll need:
**Note: Please be considerate when testing experimental bots on public servers such as chat.zulip.org.**
-1. Go to your Zulip account and
- [add a bot](/help/add-a-bot-or-integration). Use **Generic bot** as the bot type.
+{start_tabs}
-1. Download the bot's `zuliprc` configuration file to your computer.
+1. [Create a bot](/help/add-a-bot-or-integration), making sure to select
+ **Generic bot** as the **Bot type**.
-1. Download the `zulip_bots` Python package to your computer using `pip3 install zulip_bots`.
+1. [Download the bot's `zuliprc` file](/api/configuring-python-bindings#download-a-zuliprc-file).
- *Note: Click
- [here](
- writing-bots#installing-a-development-version-of-the-zulip-bots-package)
- to install the latest development version of the package.*
+1. Use the following command to install the
+ [`zulip_bots` Python package](https://pypi.org/project/zulip-bots/):
-1. Start the bot process on your computer.
+ pip3 install zulip_bots
- * Run
- ```
- zulip-run-bot --config-file ~/path/to/zuliprc
- ```
+1. Use the following command to start the bot process *(replacing
+ `~/path/to/zuliprc` with the path to the `zuliprc` file you downloaded above)*:
- (replacing `~/path/to/zuliprc` with the path to the `zuliprc` file you downloaded above).
+ zulip-run-bot --config-file ~/path/to/zuliprc
- * Check the output of the command. It should include the following line:
+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...
+ INFO:root:starting message handling...
- Congrats! Your bot is running.
+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 stream.
-1. To talk with the bot, at-mention its name, like `@**bot-name**`.
+!!! tip ""
+
+ 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).
+
+{end_tabs}
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](/api/deploying-bots) it on a server using the
-Zulip Botserver.
+environment where it'll stay up, by [deploying](/api/deploying-bots) it on a
+server using the Zulip Botserver.
## Common problems
@@ -63,3 +66,9 @@ Zulip Botserver.
the Vagrant environment.
* Some bots require Python 3. Try switching to a Python 3 environment before running
your bot.
+
+## Related articles
+
+* [Non-webhook integrations](/api/non-webhook-integrations)
+* [Deploying bots](/api/deploying-bots)
+* [Writing bots](/api/writing-bots)
diff --git a/api_docs/writing-bots.md b/api_docs/writing-bots.md
index 2667928a90..dbd5b587b3 100644
--- a/api_docs/writing-bots.md
+++ b/api_docs/writing-bots.md
@@ -17,23 +17,41 @@ On this page you'll find:
## Installing a development version of the Zulip bots package
-1. `git clone https://github.com/zulip/python-zulip-api.git` - clone the [python-zulip-api](
- https://github.com/zulip/python-zulip-api) repository.
+{start_tabs}
-2. `cd python-zulip-api` - navigate into your cloned repository.
+1. Clone the [python-zulip-api](https://github.com/zulip/python-zulip-api)
+ repository:
-3. `python3 ./tools/provision` - install all requirements in a Python virtualenv.
+ ```
+ git clone https://github.com/zulip/python-zulip-api.git
+ ```
-4. The output of `provision` will end with a command of the form `source .../activate`;
- run that command to enter the new virtualenv.
+1. Navigate into your cloned repository:
-5. *Finished*. You should now see the name of your venv preceding your prompt,
- e.g. `(zulip-api-py3-venv)`.
+ ```
+ cd python-zulip-api
+ ```
-*Hint: `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.*
+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)`.
+
+!!! 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}
## Writing a bot
@@ -512,3 +530,10 @@ The long-term plan for this bot system is to allow the same
received from Zulip's outgoing webhooks integration.
* For bots merged into the mainline Zulip codebase, enabled via a
button in the Zulip web UI, with no code deployment effort required.
+
+## Related articles
+
+* [Non-webhook integrations](/api/non-webhook-integrations)
+* [Running bots](/api/running-bots)
+* [Deploying bots](/api/deploying-bots)
+* [Configuring the Python bindings](/api/configuring-python-bindings)