diff --git a/static/images/help/add_a_new_bot.png b/static/images/help/add_a_new_bot.png deleted file mode 100644 index 9901b74ba4..0000000000 Binary files a/static/images/help/add_a_new_bot.png and /dev/null differ diff --git a/static/images/help/bot_example.png b/static/images/help/bot_example.png deleted file mode 100644 index fda522cd57..0000000000 Binary files a/static/images/help/bot_example.png and /dev/null differ diff --git a/static/images/help/bot_types.png b/static/images/help/bot_types.png deleted file mode 100644 index d819311707..0000000000 Binary files a/static/images/help/bot_types.png and /dev/null differ diff --git a/templates/zerver/help/add-a-bot-or-integration.md b/templates/zerver/help/add-a-bot-or-integration.md index a7b38b9241..32d6010111 100644 --- a/templates/zerver/help/add-a-bot-or-integration.md +++ b/templates/zerver/help/add-a-bot-or-integration.md @@ -1,62 +1,27 @@ -# Add a bot or integration +# Add a bot -Bots and integrations are features that are accessible to all members of an organization. +By default, anyone can add a bot to a Zulip organization. +A bot that sends content to or from another product is often called an +**integration**. + +Organization administrators can also +[restrict bot creation](/help/restrict-bot-creation). Any bot that is added +is visible and available for anyone to use. ## Add a bot {settings_tab|your-bots} -2. On this page, under the **Add a new bot** view, enter the bot type, - a name, an email, and optionally an avatar for your bot. - Then click the **Create bot** button to create your bot. +2. Click **Add a new bot**. - ![Bots page](/static/images/help/add_a_new_bot.png) +3. Fill out the fields, and click **Create bot**. -3. An entry such as the following should appear above the **Add a new bot** view, confirming -the creation of your bot. +!!! tip "" + Our [guide to bots](/help/bots-and-integrations) has more information about + the various fields. + Nearly all third-party integrations should use **Incoming webhook** + as the **bot type**. - ![Example bot](/static/images/help/bot_example.png) - -4. You now have access to your bot's API key and API -configuration file (`.zuliprc`) which you will need for integrations that you would like -to use with this bot. You can click on the download -() icon to download your `.zuliprc` file. - -### Bot types - -You can create three types of bots: - -![Bot types](/static/images/help/bot_types.png) - -* **Generic bot:** A generic bot can send *and* receive messages. - Choose this type if you want to: - * *test* and deploy a simple Python bot using the [Zulip bots]( - https://github.com/zulip/python-zulip-api/tree/master/zulip_bots) framework. - * interact with Zulip using the [Zulip Python API]( - https://github.com/zulip/python-zulip-api/tree/master/zulip). - -* **Incoming webhook:** The API keys for such bots are limited to - only sending messages and can't receive messages. Thus, this bot - type lessens the security risks associated with exposing such API - keys to third-party services. - Choose this type if you want to: - * deploy one of our [integrations](/integrations). - * develop your own integration that posts to Zulip. Note that - `Incoming Webhook` integrations can only be developed in the [Zulip repository]( - https://github.com/zulip/zulip/tree/master/zerver/webhooks). - -* **Outgoing webhook:** Bots of this type are the same as a **Generic bot**, - except **Outgoing webhooks** bots have an extra field for the Endpoint URL of the - third-party service being requested. **Outgoing webhook** bots send POST requests - to this Endpoint URL. - Choose this type if you want to: - * make Zulip post messages to a URL. - * deploy Zulip's [Botserver](/api/deploying-bots). - *This is the default way of deploying bots used in production.* - -## Add an integration - -The [Integrations page](/integrations) offers a complete list of all the -integrations currently supported by Zulip. To add an integration to your -organization, select the integration that you would like to use from the list -and follow the installation instructions accordingly. +Depending on the type of bot you're creating, you may need to download its +`.zuliprc` configuration file. For that, click the **download** +() icon under the bot's name. diff --git a/templates/zerver/help/bots-and-integrations.md b/templates/zerver/help/bots-and-integrations.md new file mode 100644 index 0000000000..1288f98f28 --- /dev/null +++ b/templates/zerver/help/bots-and-integrations.md @@ -0,0 +1,74 @@ +# About bots + +Bots allow you to + +* Send content into and out of Zulip. +* Send content to and from another product. +* Automate tasks a human user could do. + +A bot that sends content to or from another product is often called an +**integration**. + +### Pre-made bots + +Zulip natively supports integrations with over 90 products, and with +hundreds more through Zapier and IFTTT. If you're looking to add an +integration with an existing product, see our +[list of integrations](/integrations), along with those of +[Zapier](https://zapier.com/apps) and [IFTTT](https://ifttt.com/search). + +## Anatomy of a bot + +You can think of a bot as a special kind of user, with limited permissions. +Each bot has a **name**, **avatar**, **email**, **bot type** and **API key**. + +* The **name** and **avatar** play the same role they do for human users. They +are the most visible attributes of a bot. + +* The **email** is not used for anything, and will likely be removed in a +future version of Zulip. + +* The **bot type** determines what the bot can and can't do (see below). + +* The **API key** is how the bot identifies itself to Zulip. Anyone with the + bot's API key can impersonate the bot. + +## Bot type + +The **bot type** determines what the bot can do. + +Bot type | Permissions | Common uses +---|---|--- +Incoming webhook | Send messages into Zulip | Third party integrations +Outgoing webhook | Send messages into Zulip, read messages where the bot is addressed | Third party integrations, most custom bots +Generic | Anything the bot creator can do | Automating tasks, bots that listen to all messages on a stream +API super bot (self-hosted only) | Anything any user can do | Mirroring + +It's generally best to pick the most restricted bot type that is sufficient +to do the task at hand. Anyone with the bot's API key can do anything the +bot can. + +A few more details: + +* **Outgoing webhook**: The bot can read private messages where the bot is a + participant, and stream messages where the bot is @-mentioned. When the + bot is PM'd or at-mentioned, it POSTs the message content to a URL of your + choice. The POST request format can be in a Zulip format or a + Slack-compatible format. + + This is the preferred bot type for interactive bots built on top of Zulip + botserver. + +* **Generic**: Note that if you truly want to impersonate yourself + (e.g. write messages that come from you, rather than from a look-a-like), + you'll need to use your **personal API key**. + +* **API super bot**: You cannot create this from the web interface. Contact + `support@zulipchat.com` if you'd like information on how to set this up. + +## Adding bots + +By default, anyone can [add a bot](/help/add-a-bot-or-integration) to a +Zulip organization, but administrators can +[restrict bot creation](/help/restrict-bot-creation). Any bot that is added +is visible and available for anyone to use. diff --git a/templates/zerver/help/include/create-a-bot-indented.md b/templates/zerver/help/include/create-a-bot-indented.md index 19cdae44b3..89734dcc58 100644 --- a/templates/zerver/help/include/create-a-bot-indented.md +++ b/templates/zerver/help/include/create-a-bot-indented.md @@ -3,5 +3,3 @@ **Incoming webhook** as the **Bot type**: ![](/static/images/help/bot_types.png) - - Fill out the rest of the fields, and click **Create bot**. diff --git a/templates/zerver/help/include/create-a-bot.md b/templates/zerver/help/include/create-a-bot.md index 3687c6d2b5..6416009195 100644 --- a/templates/zerver/help/include/create-a-bot.md +++ b/templates/zerver/help/include/create-a-bot.md @@ -3,5 +3,3 @@ **Incoming webhook** as the **Bot type**: ![](/static/images/help/bot_types.png) - -Fill out the rest of the fields, and click **Create bot**. diff --git a/templates/zerver/help/include/sidebar_index.md b/templates/zerver/help/include/sidebar_index.md index 45d70fd659..95483fd143 100644 --- a/templates/zerver/help/include/sidebar_index.md +++ b/templates/zerver/help/include/sidebar_index.md @@ -77,7 +77,8 @@ * [Troubleshoot desktop notifications](/help/troubleshooting-desktop-notifications) ## Tools & customization -* [Bots and integrations](/help/add-a-bot-or-integration) +* [Bots and integrations](/help/bots-and-integrations) +* [Add a bot or integration](/help/add-a-bot-or-integration) * [Night mode](/help/night-mode) * [Enable emoticon translations](/help/enable-emoticon-translations) * [Manage your uploaded files](/help/manage-your-uploaded-files)