Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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

This commit is contained in:
Shubham Dhama 2018-09-26 02:04:22 +05:30 committed by Rishi Gupta
parent c9765da47d
commit 8c6424a4bd
8 changed files with 94 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
static/images/help/add_a_new_bot.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 20 KiB

BIN
static/images/help/bot_example.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 13 KiB

BIN
static/images/help/bot_types.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 17 KiB

71
templates/zerver/help/add-a-bot-or-integration.md
View File

@ -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
(<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.
Depending on the type of bot you're creating, you may need to download its
`.zuliprc` configuration file. For that, click the **download**
(<i class="icon-vector-download-alt"></i>) icon under the bot's name.

74
templates/zerver/help/bots-and-integrations.md Normal file
View File

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

2
templates/zerver/help/include/create-a-bot-indented.md
View File

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

2
templates/zerver/help/include/create-a-bot.md
View File

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

3
templates/zerver/help/include/sidebar_index.md
View File

@ -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)