user docs: Split and update add-a-bot-or-integration.md.

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,
+2. Click **Add a new bot**.
-   a name, an email, and optionally an avatar for your bot.
-   Then click the **Create bot** button to create your 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
+!!! tip ""
-the creation of your bot.
+    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)
+Depending on the type of bot you're creating, you may need to download its
-
+`.zuliprc` configuration file. For that, click the **download**
-4. You now have access to your bot's API key and API
+(<i class="icon-vector-download-alt"></i>) icon under the bot's name.
-configuration file (`.zuliprc`) which you will need for integrations that you would like
-to use with this bot. You can click on the download
-(<i class="icon-vector-download-alt"></i>) 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.

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 <!-- # ignorelongline -->
+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.

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**.

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**.

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)