paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-10-23 04:52:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

help: Organize details on bots overview page.

Browse Source 
Also document can_forge_sender permission.
This commit is contained in:
Alya Abbott
2025-09-17 09:07:00 -07:00
committed by Tim Abbott
parent 9e3fea7ed3
commit be0fc99b58
1 changed files with 38 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
starlight_help/src/content/docs/bots-overview.mdx
View File

@@ -42,31 +42,32 @@ The **bot type** determines what the bot can do.
| Incoming webhook | Limited to only sending messages into Zulip | Automated notifications into Zulip | | Incoming webhook | Limited to only sending messages into Zulip | Automated notifications into Zulip |
| Outgoing webhook | Generic bot that also receives new messages via HTTP post requests | Third party integrations, most custom bots | | Outgoing webhook | Generic bot that also receives new messages via HTTP post requests | Third party integrations, most custom bots |
It's generally best to pick the most restricted bot type that is sufficient A **generic** bot acts like a normal Zulip user that can only access Zulip via
to do the task at hand. Anyone with the bot's API key can do anything the the API. There's a handful of actions bots can't take, including creating other
bot can. bots.
A few more details: An **outgoing webhook** bot can read direct messages where the bot
is a participant, and channel messages where the bot is
[mentioned](/help/mention-a-user-or-group). When the bot is DM'd or
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.
* Bots can send messages to any channel that their owner can, Use the most limited bot type that supports your integration. Anyone with the
inheriting their owner's [sending permissions](/help/channel-posting-policy). bot's API key can do anything the bot can, so giving bots unnecessary
* Bots can be subscribed to channels, and their role can be modified if permissions can expose your organization to unnecessary risk.
they need to have permission to do administrative actions.
* [Channel permissions](/help/channel-permissions) are the same for bots ## Channel permissions for bots
as for other users. Therefore, for private channels with protected
history, a bot can only access messages sent after it was subscribed Bots can be subscribed to channels, and assigned [channel
to the channel. permissions](/help/channel-permissions) just like human users. In private
* **Generic**: A generic bot is like a normal Zulip user account that channels with protected history, a bot can only access messages sent after it
cannot log in via a browser. Note that if you truly want to was subscribed to the channel.
impersonate yourself (e.g., write messages that come from your Zulip
account), you'll need to use your **personal API key**. Bots can send messages to any channel that their owner can, inheriting their
* **Outgoing webhook**: The bot can read direct messages where the bot owner's [sending permissions](/help/channel-posting-policy). You can give a bot
is a participant, and channel messages where the bot is channel management permissions, just like you would for a human user.
[mentioned](/help/mention-a-user-or-group). When the bot is DM'd or
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.
## Adding bots ## Adding bots
@@ -75,6 +76,20 @@ Zulip organization, but administrators can
[restrict bot creation](/help/restrict-bot-creation). Any bot that is added [restrict bot creation](/help/restrict-bot-creation). Any bot that is added
is visible and available for anyone to use. is visible and available for anyone to use.
## Integrations that act on behalf of users
If you want an integration to impersonate you (e.g., write messages that come
from your Zulip account), use your [personal API key](/api/api-keys), rather
than a bot's API key. You won't need to create a bot.
If you need a bot to send messages on behalf of multiple users, ask [Zulip
support](mailto:support@zulip.com) or your server administrator to run the
`manage.py change_user_role can_forge_sender` command to give a bot
permission to send messages as users in your organization. Bots with the
`can_forge_sender` permission can also see the names of all channels,
including private channels. This is important for implementing integrations
like the Jabber and IRC mirrors.
## Related articles ## Related articles
* [Integrations overview](/help/integrations-overview) * [Integrations overview](/help/integrations-overview)