zulip/zerver/webhooks/slack/doc.md

Forward Slack messages into Zulip

Forward messages sent to your Slack workspace's public channels into Zulip!

This integration lets you choose how to organize your Slack messages in Zulip. You can:

• Send messages from each Slack channel into a matching Zulip channel.
• Send messages from each Slack channel into a matching Zulip topic.
• Send all Slack messages into a single Zulip topic.

If you'd like to forward messages in both directions (Slack to Zulip and Zulip to Slack), please see separate instructions for how to set this up.

If you are looking to quickly move your Slack integrations to Zulip, check out Zulip's Slack-compatible incoming webhook.

!!! warn ""

Using [Slack's legacy Outgoing Webhook service][5] is no longer
recommended. Follow these instructions to switch to the new
[Slack Events API][3].

{start_tabs}

1. {!create-an-incoming-webhook.md!}

2. {!generate-webhook-url-basic.md!}

   To send messages from each Slack channel into a matching Zulip channel, enable the Send all notifications to a single topic option, and add &channels_map_to_topics=0 to the generated URL. For each public channel in your Slack workspace, be sure to create a Zulip channel with the same name.

   To send messages from each Slack channel into a matching Zulip topic, disable the Send all notifications to a single topic option when generating the URL. Add &channels_map_to_topics=1 to the generated URL.

   To send all Slack messages into a single Zulip topic, enable the Send all notifications to a single topic option, with no further modifications.

3. (optional) If you're setting up a Slack bridge to forward Zulip messages into your Slack workspace, replace the value of the ?api_key= parameter in the integration URL you generated with the API key of the Generic bot you're using for the Slack bridge.

4. Create a new Slack app, and open it. Navigate to the OAuth & Permissions menu, and scroll down to the Scopes section.

5. Make sure Bot Token Scopes includes channels:history, channels:read, and users:read. If you're setting up a bidirectional bridge, make sure to also include the chat:write scope.

   !!! tip ""

    See the [required bot token scopes](#required-bot-token-scopes)
    section for details about these scopes.
   

6. Scroll to the OAuth Tokens for Your Workspace section in the same menu, and click Install to Workspace.

7. Copy the Slack Bot User OAuth Token, and add it to the end of your integration URL as &slack_app_token=BOT_OAUTH_TOKEN.

8. Go to the Event Subscriptions menu, toggle Enable Events, and enter your updated integration URL in the Request URL field.

9. In the same menu, scroll down to the Subscribe to bot events section, and click on Add Bot User Event. Select the message.channels event.

10. Add the bot as an app to the Slack channels you'd like to receive notifications from.

{end_tabs}

{!congrats.md!}

Required bot token scopes

• channels:history is required by Slack's Event API's message.channels event. This is used to send new messages from Slack to Zulip.

• channels:read is required for Slack's conversations.info endpoint. This is used to get the name of the Slack channel a message came from.

• For a bidirectional bridge setup, the chat:write is also required for Slack's chat.postMessage method. This is used to send new messages from Zulip to Slack.

• users:read is required to call Slack's users.info endpoint. This is used to get the name of the Slack message's sender.

Related documentation

• Forward messages Slack <-> Zulip (both directions)

• Slack Events API documentation

• Slack Apps

• Zulip's Slack-compatible incoming webhook

{!webhooks-url-specification.md!}