mirror of https://github.com/zulip/zulip.git
api-docs: Use `start_tabs` formatting and add "Related articles".
- Updates API docs that have numbered instructions to use the
`{start_tabs}` formatting we use in the help center.
- Cleans up formatting and revises documentation that shouldn't
be formatted as a numbered instructions block.
- Cross-links related articles.
Fixes #28876.
This commit is contained in:
David Rosa
Tim Abbott
parent
96daef400e
commit
3c0cb4c6a2
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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,15 +233,14 @@ 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
|
||||
- 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
|
||||
- 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:
|
||||
|
|
@ -243,3 +252,9 @@ Botserver with SSL using an `nginx` or `Apache` reverse proxy and
|
|||
<h1>Method Not Allowed</h1>
|
||||
<p>The method is not allowed for the requested URL.</p>
|
||||
```
|
||||
|
||||
## Related articles
|
||||
|
||||
* [Non-webhook integrations](/api/non-webhook-integrations)
|
||||
* [Running bots](/api/running-bots)
|
||||
* [Writing bots](/api/writing-bots)
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
- 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](
|
||||
- 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
|
||||
- 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.
|
||||
|
||||
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)
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
1. Use the following command to start the bot process *(replacing
|
||||
`~/path/to/zuliprc` with the path to the `zuliprc` file you downloaded above)*:
|
||||
|
||||
* Run
|
||||
```
|
||||
zulip-run-bot <bot-name> --config-file ~/path/to/zuliprc
|
||||
```
|
||||
|
||||
(replacing `~/path/to/zuliprc` with the path to the `zuliprc` file you downloaded above).
|
||||
|
||||
* 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...
|
||||
|
||||
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)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
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.*
|
||||
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)
|
||||
|
|
|
|||
Loading…
Reference in New Issue