upstream-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, open the Where to send notifications dropdown and select Matching Zulip channel.

   To send messages from each Slack channel into a matching Zulip topic, open the Topics to use dropdown, and select Topics named after Slack channels.

   To send all Slack messages into a single Zulip topic, open the Topics to use dropdown, and select Send all notifications to a single topic.

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 section in the same menu, and click Install to Workspace. Grant the app permission to access your workspace by clicking Allow when prompted.

7. You will immediately see a Bot User OAuth Token. Copy it 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.

Caveats

• Mentions in messages are not converted to Zulip mentions.

• Notifications will be delayed by a few seconds.

• Some emojis exported from Slack will display as :emojiname:, if the emoji name is not present in the emoji database used by Zulip.

• Threads will appear in the main topic instead of in separate topics.

The following data is not included:

• Custom emoji

• Message attachments

• Message edit history

• Message reactions

Related documentation

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

• Slack Events API documentation

• Slack Apps

• Zulip's Slack-compatible incoming webhook

{!webhooks-url-specification.md!}