From ff9e65ce0f95ca882517e9041c1e805e4affef35 Mon Sep 17 00:00:00 2001 From: Kate Mueller Date: Mon, 19 Aug 2024 12:26:47 -0400 Subject: [PATCH] DOC-975: Update Slack credential to High priority template (#2283) Co-authored-by: aya <15815271+ayatnkw@users.noreply.github.com> --- .../builtin/app-nodes/n8n-nodes-base.slack.md | 150 ++++++++++++------ .../integrations/builtin/credentials/slack.md | 98 ++++++++---- .../n8n-nodes-base.slacktrigger.md | 51 ++++-- 3 files changed, 205 insertions(+), 94 deletions(-) diff --git a/docs/integrations/builtin/app-nodes/n8n-nodes-base.slack.md b/docs/integrations/builtin/app-nodes/n8n-nodes-base.slack.md index 517338919..49690e4cc 100644 --- a/docs/integrations/builtin/app-nodes/n8n-nodes-base.slack.md +++ b/docs/integrations/builtin/app-nodes/n8n-nodes-base.slack.md @@ -9,6 +9,7 @@ priority: high # Slack Use the Slack node to automate work in Slack, and integrate Slack with other applications. n8n has built-in support for a wide range of Slack features, including creating, archiving, and closing channels, getting users and files, as well as deleting messages. + On this page, you'll find a list of operations the Slack node supports and links to more resources. /// note | Credentials @@ -17,53 +18,54 @@ Refer to [Slack credentials](/integrations/builtin/credentials/slack/) for guida ## Operations -* Channel - * Archive - * Close - * Create - * Get - * Get many - * History - * Invite - * Join - * Kick - * Leave - * Member - * Open - * Rename - * Replies - * Sets purpose - * Sets topic - * Unarchive -* File - * Get - * Get many - * Upload -* Message - * Delete - * Get permalink - * Search - * Send - * Update -* Reaction - * Add - * Get - * Remove -* Star - * Add - * Delete - * Get many -* User - * Get - * Get many - * Get user's status - * Update user's profile -* User Group - * Create - * Disable - * Enable - * Get many - * Update +* **Channel** + * **Archive** a channel. + * **Close** a direct message or multi-person direct message. + * **Create** a public or private channel-based conversation. + * **Get** information about a channel. + * **Get Many**: Get a list of channels in Slack. + * **History**: Get a channel's history of messages and events. + * **Invite** a user to a channel. + * **Join** an existing channel. + * **Kick**: Remove a user from a channel. + * **Leave** a channel. + * **Member**: List the members of a channel. + * **Open** or resume a direct message or multi-person direct message. + * **Rename** a channel. + * **Replies**: Get a thread of messages posted to a channel. + * **Sets purpose** of a channel. + * **Sets topic** of a channel. + * **Unarchive** a channel. +* **File** + * **Get** a file. + * **Get Many**: Get and filter team files. + * **Upload**: Create or upload an existing file. +* **Message** + * **Delete** a message + * **Get permalink**: Get a message's permalink. + * **Search** for messages + * **Send** a message + * **Update** a message +* **Reaction** + * **Add** a reaction to a message. + * **Get** a message's reactions. + * **Remove** a reaction from a message. +* **Star** + * **Add** a star to an item. + * **Delete** a star from an item. + * **Get Many**: Get a list of an authenticated user's stars. +* **User** + * **Get** information about a user. + * **Get Many**: Get a list of users. + * **Get User's Profile**. + * **Get User's Status**. + * **Update User's Profile**. +* **User Group** + * **Create** a user group. + * **Disable** a user group. + * **Enable** a user group. + * **Get Many**: Get a list of user groups. + * **Update** a user group. ## Templates and examples @@ -74,4 +76,58 @@ Refer to [Slack credentials](/integrations/builtin/credentials/slack/) for guida Refer to [Slack's documentation](https://api.slack.com/){:target=_blank .external-link} for more information about the service. +## Required scopes + +Once you create a Slack app for your [Slack credentials](/integrations/builtin/credentials/slack/), you must add the appropriate scopes to your Slack app for this node to work. Start with the scopes listed in the [Scopes | Slack credentials](/integrations/builtin/credentials/slack/#scopes) page. + +If those aren't enough, use the table below to look up the resource and operation you want to use, then follow the link to Slack's API documentation to find the correct scopes. + + + +| **Resource** | **Operation** | **Slack API method** | +| --- | --- | --- | +| Channel | Archive | [conversations.archive](https://api.slack.com/methods/conversations.archive){:target=blank .external-link} | +| Channel | Close | [conversations.close](https://api.slack.com/methods/conversations.close){:target=blank .external-link} | +| Channel | Create | [conversations.create](https://api.slack.com/methods/conversations.create){:target=blank .external-link} | +| Channel | Get | [conversations.info](https://api.slack.com/methods/conversations.info){:target=blank .external-link} | +| Channel | Get Many | [conversations.list](https://api.slack.com/methods/conversations.list){:target=blank .external-link} | +| Channel | History | [conversations.history](https://api.slack.com/methods/conversations.history){:target=blank .external-link} | +| Channel | Invite | [conversations.invite](https://api.slack.com/methods/conversations.invite){:target=blank .external-link} | +| Channel | Join | [conversations.join](https://api.slack.com/methods/conversations.join){:target=blank .external-link} | +| Channel | Kick | [conversations.kick](https://api.slack.com/methods/conversations.kick){:target=blank .external-link} | +| Channel | Leave | [conversations.leave](https://api.slack.com/methods/conversations.leave){:target=blank .external-link} | +| Channel | Member | [conversations.members](https://api.slack.com/methods/conversations.members){:target=blank .external-link} | +| Channel | Open | [conversations.open](https://api.slack.com/methods/conversations.open){:target=blank .external-link} | +| Channel | Rename | [conversations.rename](https://api.slack.com/methods/conversations.rename){:target=blank .external-link} | +| Channel | Replies | [conversations.replies](https://api.slack.com/methods/conversations.replies){:target=blank .external-link} | +| Channel | Set Purpose | [conversations.setPurpose](https://api.slack.com/methods/conversations.setPurpose){:target=blank .external-link} | +| Channel | Set Topic | [conversations.setTopic](https://api.slack.com/methods/conversations.setTopic){:target=blank .external-link} | +| Channel | Unarchive | [conversations.unarchive](https://api.slack.com/methods/conversations.unarchive){:target=blank .external-link} | +| File | Get | [files.info](https://api.slack.com/methods/files.info){:target=blank .external-link} | +| File | Get Many | [files.list](https://api.slack.com/methods/files.list){:target=blank .external-link} | +| File | Upload | [files.upload](https://api.slack.com/methods/files.upload){:target=blank .external-link} | +| Message | Delete | [chat.delete](https://api.slack.com/methods/chat.delete){:target=blank .external-link} | +| Message | Get Permalink | [chat.getPermalink](https://api.slack.com/methods/chat.getPermalink){:target=blank .external-link} | +| Message | Search | [search.messages](https://api.slack.com/methods/search.messages){:target=blank .external-link} | +| Message | Send | [chat.postMessage](https://api.slack.com/methods/chat.postMessage){:target=blank .external-link} | +| Message | Update | [chat.update](https://api.slack.com/methods/chat.update){:target=blank .external-link} | +| Reaction | Add | [reactions.add](https://api.slack.com/methods/reactions.add){:target=blank .external-link} | +| Reaction | Get | [reactions.get](https://api.slack.com/methods/reactions.get){:target=blank .external-link} | +| Reaction | Remove | [reactions.remove](https://api.slack.com/methods/reactions.remove){:target=blank .external-link} | +| Star | Add | [stars.add](https://api.slack.com/methods/stars.add){:target=blank .external-link} | +| Star | Delete | [stars.remove](https://api.slack.com/methods/stars.remove){:target=blank .external-link} | +| Star | Get Many | [stars.list](https://api.slack.com/methods/stars.list){:target=blank .external-link} | +| User | Get | [users.info](https://api.slack.com/methods/users.info){:target=blank .external-link} | +| User | Get Many | [users.list](https://api.slack.com/methods/users.list){:target=blank .external-link} | +| User | Get User's Profile | [users.profile.get](https://api.slack.com/methods/users.profile.get){:target=blank .external-link} | +| User | Get User's Status | [users.getPresence](https://api.slack.com/methods/users.getPresence){:target=blank .external-link} | +| User | Update User's Profile | [users.profile.set](https://api.slack.com/methods/users.profile.set){:target=blank .external-link} | +| User Group | Create | [usergroups.create](https://api.slack.com/methods/usergroups.create){:target=blank .external-link} | +| User Group | Disable | [usergroups.disable](https://api.slack.com/methods/usergroups.disable){:target=blank .external-link} | +| User Group | Enable | [usergroups.enable](https://api.slack.com/methods/usergroups.enable){:target=blank .external-link} | +| User Group | Get Many | [usergroups.list](https://api.slack.com/methods/usergroups.list){:target=blank .external-link} | +| User Group | Update | [usergroups.update](https://api.slack.com/methods/usergroups.update){:target=blank .external-link} | + + + --8<-- "_snippets/integrations/builtin/app-nodes/operation-not-supported.md" diff --git a/docs/integrations/builtin/credentials/slack.md b/docs/integrations/builtin/credentials/slack.md index 42072482a..b4ab952f2 100644 --- a/docs/integrations/builtin/credentials/slack.md +++ b/docs/integrations/builtin/credentials/slack.md @@ -13,16 +13,14 @@ You can use these credentials to authenticate the following nodes: - [Slack](/integrations/builtin/app-nodes/n8n-nodes-base.slack/) - [Slack Trigger](/integrations/builtin/trigger-ndoes/n8n-nodes-base.slacktrigger/) - -## Prerequisites - -- Create a [Slack](https://slack.com/){:target=_blank .external-link} account. -- Create a Slack app. Refer to the Slack API [Quickstart](https://api.slack.com/quickstart){:target=_blank .external-link} for more information. - ## Supported authentication methods -- API access token -- OAuth2 +- API access token: + - Required for the [Slack Trigger](/integrations/builtin/trigger-nodes/n8n-nodes-base.slacktrigger/) node. + - Works with the [Slack](/integrations/builtin/app-nodes/n8n-nodes-base.slack/) node, but not recommended. +- OAuth2: + - Recommended method for the [Slack](/integrations/builtin/app-nodes/n8n-nodes-base.slack/) node. + - Doesn't work with the [Slack Trigger](/integrations/builtin/trigger-nodes/n8n-nodes-base.slacktrigger/) node. ## Related resources @@ -30,7 +28,7 @@ Refer to [Slack's API documentation](https://api.slack.com/apis){:target=_blank ## Using API access token -To configure this credential, you'll need: +To configure this credential, you'll need a [Slack](https://slack.com/){:target=_blank .external-link} account and: - An **Access Token** @@ -43,26 +41,40 @@ To generate an access token, create a Slack app: 5. Select **Create App**. 6. In **Basic Information > Building Apps for Slack**, select **Add features and functionality**. 7. Select **Permissions**. -8. In the **Scopes** section: - * If you want your app to act on behalf of users who authorize the app, add the required scopes under the **User Token Scopes** section. - * If you're building a bot, add the required scopes under the **Bot Token Scopes** section. - - /// note | Scopes - Scopes determine what permissions an app has. Refer to Slack's [Permission scopes](https://api.slack.com/scopes){:target=_blank .external-link} documentation for a list of scopes. - /// - -8. After you've added scopes, go up to the **OAuth Tokens for Your Workspace** section and select **Install to Workspace**. You must be a Slack workspace admin to complete this action. -9. Select **Allow**. -10. You'll return to the **OAuth Tokens for your Workspace** section, which now displays a **Bot User OAuth Token**. -10. Copy that token and enter it into the n8n credential. +8. In the **Scopes** section, select appropriate scopes for your app. Refer to [Scopes](#scopes) for a list of recommended scopes. +9. After you've added scopes, go up to the **OAuth Tokens for Your Workspace** section and select **Install to Workspace**. You must be a Slack workspace admin to complete this action. +10. Select **Allow**. +11. Go to **Features** > **OAuth Tokens for your Workspace** if you aren't automatically directed there. +12. Copy the **Bot User OAuth Token** and enter it as the **Access Token** in your n8n credential. +13. If you're using this credential for the [Slack Trigger](/integrations/builtin/trigger-nodes/n8n-nodes-base.slacktrigger/), follow the steps in [Slack Trigger configuration](#slack-trigger-configuration) to finish setting up your app. Refer to the Slack API [Quickstart](https://api.slack.com/quickstart){:target=_blank .external-link} for more information. +### Slack Trigger configuration + +To use your Slack app with the [Slack Trigger](/integrations/builtin/trigger-nodes/n8n-nodes-base.slacktrigger/) node: + +1. Go to **Features** > **Event Subscriptions**. +2. Turn on the **Enable Events** control. +3. In n8n, copy the **Webhook URL** and enter it as the **Request URL** in your Slack app. + + /// note | Request URL + Slack only allows one request URL per app. If you want to test your workflow, you'll need to do one of the following: + + - Test with your **Test URL** first, then change your Slack app to use the **Production URL** once you've verified everything's working + - Use the **Production URL** with execution logging. + /// + +4. Once verified, select the bot events to subscribe to. Use the **Trigger on** field in n8n to filter these requests. + - To use an event not in the list, add it as a bot event and select **Any Event** in the n8n node. + +Refer to [Quickstart | Configuring the app for event listening](https://api.slack.com/quickstart#listening){:target=_blank .external-link} for more information. + ## Using OAuth2 --8<-- "_snippets/integrations/builtin/credentials/cloud-oauth-button.md" -If you need to configure OAuth2 from scratch, you'll need: +If you're [self-hosting n8n](/hosting/) and need to configure OAuth2 from scratch, you'll need a [Slack](https://slack.com/){:target=_blank .external-link} account and: - A **Client ID** - A **Client Secret** @@ -82,16 +94,38 @@ To get both, create a Slack app: 8. Copy the **OAuth Callback URL** from n8n and enter it as the new Redirect URL in Slack. 9. Select **Add**. 10. Select **Save URLs**. -11. In the **Scopes** section: - * If you want your app to act on behalf of users who authorize the app, add the required scopes under the **User Token Scopes** section. - * If you're building a bot, add the required scopes under the **Bot Token Scopes** section. - - /// note | Scopes - Scopes determine what permissions an app has. Refer to Slack's [Permission scopes](https://api.slack.com/scopes){:target=_blank .external-link} documentation for a list of scopes. - /// - +11. In the **Scopes** section, select appropriate scopes for your app. Refer to [Scopes](#scopes) for a list of scopes. 13. After you've added scopes, go up to the **OAuth Tokens for Your Workspace** section and select **Install to Workspace**. You must be a Slack workspace admin to complete this action. 14. Select **Allow**. -15. At this point, you should be able select the OAuth button in your n8n credential to connect. +15. At this point, you should be able to select the OAuth button in your n8n credential to connect. -Refer to the Slack API [Quickstart](https://api.slack.com/quickstart){:target=_blank .external-link} for more information. Refer to the Slack [Installing with OAuth](https://api.slack.com/authentication/oauth-v2){:target=_blank .external-link} documentation for more details on the OAuth flow itself. \ No newline at end of file +Refer to the Slack API [Quickstart](https://api.slack.com/quickstart){:target=_blank .external-link} for more information. Refer to the Slack [Installing with OAuth](https://api.slack.com/authentication/oauth-v2){:target=_blank .external-link} documentation for more details on the OAuth flow itself. + +## Scopes + +Scopes determine what permissions an app has. + +* If you want your app to act on behalf of users who authorize the app, add the required scopes under the **User Token Scopes** section. +* If you're building a bot, add the required scopes under the **Bot Token Scopes** section. + +Here's the list of scopes the OAuth credential requires, which are a good starting point: + +| **Scope name** | **Notes** | +| --- | --- | +| `channels:read` | | +| `channels:write` | Not available as a bot token scope | +| `chat:write` | | +| `files:read` | | +| `files:write` | | +| `groups:read` | | +| `im:read` | | +| `mpim:read` | | +| `reactions:read` | | +| `reactions:write` | | +| `stars:read`| Not available as a bot token scope | +| `stars:write` | Not available as a bot token scope | +| `usergroups:read` | | +| `usergroups:write` | | +| `users.profile:read` | | +| `users.profile:write` | Not available as a bot token scope | +| `users:read` | | diff --git a/docs/integrations/builtin/trigger-nodes/n8n-nodes-base.slacktrigger.md b/docs/integrations/builtin/trigger-nodes/n8n-nodes-base.slacktrigger.md index ede87a313..d3e0a4b8c 100644 --- a/docs/integrations/builtin/trigger-nodes/n8n-nodes-base.slacktrigger.md +++ b/docs/integrations/builtin/trigger-nodes/n8n-nodes-base.slacktrigger.md @@ -17,16 +17,40 @@ You can find authentication information for this node [here](/integrations/built /// note | Examples and templates For usage examples and templates to help you get started, refer to n8n's [Slack integrations](https://n8n.io/integrations/slack-trigger/){:target=_blank .external-link} page. /// + ## Events -* Any Event -* Bot / App Mention -* File Made Public -* File Shared -* New Message Posted to Channel -* New Public Channel Created -* New User -* Reaction Added +* **Any Event**: The node triggers on any event in Slack. +* **Bot / App Mention**: The node triggers when your bot or app is [mentioned](https://slack.com/help/articles/205240127-Use-mentions-in-Slack){:target=_blank .external-link} in a channel the app is in. +* **File Made Public**: The node triggers when a file is [made public](https://slack.com/help/articles/4412651915539-Manage-public-file-sharing){:target=_blank .external-link}. +* **File Shared**: The node triggers when a file is [shared](https://slack.com/help/articles/201330736-Add-files-to-Slack){:target=_blank .external-link} in a channel the app is in. +* **New Message Posted to Channel**: The node triggers when a new message is posted to a channel the app is in. +* **New Public Channel Created**: The node triggers when a new [public channel](https://slack.com/help/articles/360017938993-What-is-a-channel){:target=_blank .external-link} is created. +* **New User**: The node triggers when a new user is added to Slack. +* **Reaction Added**: The node triggers when a [reaction](https://slack.com/help/articles/202931348-Use-emoji-and-reactions){:target=_blank .external-link} is added to a message the app is added to. + +## Parameters + +Once you've set the events to trigger on, use the remaining parameters to further define the node's behavior: + +* **Watch Whole Workspace**: Whether the node should watch for the selected **Events** in all channels in the workspace (turned on) or not (turned off, default). + + ///warning | Caution + This will use one execution for every event in any channel your bot or app is in. Use with caution! + /// + +* **Channel to Watch**: Select the channel your node should watch for the selected **Events**. This parameter only appears if you don't turn on **Watch Whole Workspace**. You can select a channel: + * **From list**: The node uses your credential to look up a list of channels in the workspace so you can select the channel you want. + * **By ID**: Enter the ID of a channel you want to watch. Slack displays the channel ID at the bottom of the channel details with a one-click copy button. + * **By URL**: Enter the URL of the channel you want to watch, formatted as `https://app.slack.com/client/`. +* **Download Files**: Whether to download files and use them in the node's output (turned on) or not (turned off, default). Use this parameter with the **File Made Public** and **File Shared** events. + +## Options + +You can further refine the node's behavior when you **Add Option**s: + +* **Resolve IDs**: Whether to resolve the IDs to their respective names and return them (turned on) or not (turned off, default). +* **Usernames or IDs to ignore**: Select usernames or enter a comma-separated string of encoded user IDs to ignore events from. Choose from the list, or specify IDs using an [expression](/code/expressions/). ## Related resources @@ -36,13 +60,10 @@ View [example workflows and related content](https://n8n.io/integrations/slack-t Refer to [Slack's documentation](https://api.slack.com/apis/connections/events-api){:target=_blank .external-link} for details about their API. -## Slack configuration +## Required scopes -To use this node you first need to create an application in Slack and enable event subscriptions. For the **Request URL** input the production or test URL displayed in the webhooks section of the node. +To use this node, you need to create an application in Slack and enable event subscriptions. Refer to [Slack credentials | Slack Trigger configuration](/integrations/builtin/credentials/slack/#slack-trigger-configuration) for more information. -/// note | Request URL -Slack only allows one request URL per app, This means if you want to test your workflow you will need to either use the production URL with execution logging or change the URL in Slack to the test URL. -/// - -Once verified you can select the bot events to subscribe to. You can use the **Events** option in the node to filter these requests. If you want to use an event not in the list you can add it as a bot event and select **Any Event** in the node. +You must add the appropriate scopes to your Slack app for this trigger node to work. +The node requires scopes for the [conversations.list](https://api.slack.com/methods/conversations.list){:target=blank .external-link} and [users.list](https://api.slack.com/methods/users.list){:target=blank .external-link} methods at minimum. Check out the [Scopes | Slack credentials](/integrations/builtin/credentials/slack/#scopes) list for a more complete list of scopes.