diff --git a/content/integrations/chat/slack/overview.mdx b/content/integrations/chat/slack/overview.mdx index 09bc3d657..0105d7097 100644 --- a/content/integrations/chat/slack/overview.mdx +++ b/content/integrations/chat/slack/overview.mdx @@ -5,23 +5,31 @@ section: Integrations > Slack layout: integrations --- -This page covers how to use Knock to send notifications to Slack. Depending on your use case, there are a few different ways to approach this integration. This documentation serves as a starting point and will cover the basics of setting up a Slack integration with Knock regardless of your use case. +This page covers how to use Knock to send notifications to Slack. You can use Knock's Slack extension to message your own team's workspace, or connect your own Slack app to build a customer-facing integration. ## What can I do with Knock's Slack integration? -Knock's Slack integration enables you to send notifications to [Slack channels](https://docs.knock.app/integrations/chat/slack/sending-a-message-to-channels) and [direct messages](https://docs.knock.app/integrations/chat/slack/sending-a-direct-message) to users via an authenticated Slack app, or via [webhooks for internal workspaces](https://docs.knock.app/integrations/chat/slack/sending-an-internal-message). You can create rich message templates using [markdown](#markdown-templates) or [Slack's block kit framework](#block-based-templates), and build integrations where customers connect your Slack app to their Slack workspaces. +Knock's Slack integration enables you to: + +- Use [internal Slack messaging](/integrations/chat/slack/sending-an-internal-message) to send messages to your team's Slack workspace. +- [Send messages to channels in your customers' workspaces](/integrations/chat/slack/sending-a-message-to-channels) using your own Slack app. +- [Send direct messages to users in your customers' workspaces](/integrations/chat/slack/sending-a-direct-message) using your own Slack app. + +You can create rich message templates using [markdown](#markdown-templates) or [Slack's Block Kit framework](#block-based-templates). This integration does not support Slack modals, slash commands, shortcuts, or interactive dialogs. -## How to connect Slack to Knock +## Connect your own Slack app + +The steps below apply when you are building a customer-facing Slack integration with your own Slack app. To send workflow messages to your own team's workspace without creating a Slack app, [create an internal Slack channel](/integrations/chat/slack/sending-an-internal-message) instead. -Knock supports multiples ways to create a Slack integration depending on your technical requirements: +Knock supports multiple ways to connect your own Slack app depending on your technical requirements: - Using Knock's managed approach with our [SlackKit components](/in-app-ui/react/slack-kit) - Using Knock's [Slack-related React hooks](https://docs.knock.app/in-app-ui/react/slack-kit#using-slackkit-headless) with your own components - Building the UI and OAuth flow entirely yourself -Regardless of your approach, you'll need a Slack app to send notifications from Knock to a Slack workspace. If you haven’t built a Slack app yet, you can get started in Slack’s app documentation. +If you haven’t built a Slack app yet, you can get started in Slack’s app documentation. Once you create your Slack app, you’ll be routed to its app management page within the Slack dashboard. It looks like this. diff --git a/content/integrations/chat/slack/sending-an-internal-message.mdx b/content/integrations/chat/slack/sending-an-internal-message.mdx index 7f84a12c6..0aed6f8af 100644 --- a/content/integrations/chat/slack/sending-an-internal-message.mdx +++ b/content/integrations/chat/slack/sending-an-internal-message.mdx @@ -1,120 +1,129 @@ --- -title: Sending a message to an internal Slack workspace -description: How to send a message to an internal Slack workspace using Knock. +title: Sending messages to your team's Slack workspace +description: Use internal Slack messaging to send Knock workflow messages to channels and people in your team's Slack workspace. tags: ["slack", "chat"] section: Integrations > Slack layout: integrations --- -In this documentation we'll cover how to send a message to an internal Slack workspace using Knock. It assumes that you have already created a Slack app and created a Slack channel in Knock as outlined in the [Slack integration](/integrations/chat/slack/overview) documentation. - -## Slack channels are connections on Objects - -In Knock, we model channels in a Slack workspace as connections on Objects. [Objects](/concepts/objects) allow you to model any resource in your system within Knock, and while their primary purpose is to act as non-user recipients, they are very flexible abstractions. +Internal Slack messaging gives your team a managed way to send workflow messages to your own Slack workspace. Connect the Knock Slack extension once, then choose a Slack channel or person as the destination for each workflow step. + +You don't need to create a Slack app, manage bot tokens, or store Slack `channel_data` on your workflow recipients. + + + The internal Slack channel is a managed Knock channel + backed by the Knock Slack extension. A Slack destination{" "} + is the channel or person in your workspace that you select on a workflow + step. One internal Slack channel can be used by many workflow steps, each + with its own destination. + + } +/> -### An overview of Objects +## Before you begin -Individual Objects exist within [a collection](/concepts/objects#collection-naming) and always have [a unique ID](/concepts/objects#the-object-identifier) or key within that collection. The Object itself can store any number and type of properties as key-value pairs. You can see some examples of possible Object structures in [the official documentation on setting Object data](/concepts/objects#sending-object-data-to-knock). +To create an internal Slack channel, you need a Knock [role](/manage-your-account/roles-and-permissions) with permission to manage both channels and extensions. After it is created, team members with permission to edit workflows can use it in workflow steps. -Let’s say you are building a devtool product like GitHub and want to set up Slack notifications whenever someone comments on an issue within a repository. First, you’ll want to create an Object to model your repository as part of the `repositories` collection: +The Knock Slack app can send to: -```javascript -import Knock from "@knocklabs/node"; -const knockClient = new Knock({ apiKey: process.env.KNOCK_API_KEY }); +- Public channels in your workspace. +- Private channels where the Knock Slack app is a member. Invite `@Knock` to a private channel before selecting it. +- Active people in your workspace via direct message. -await knockClient.objects.set("repositories", "repo-1", { - name: "My repo", -}); -``` +## Create an internal Slack channel -Once you have a repository object created, you can add the channel data for Slack as a connection on the object. + + + In the Knock dashboard, open **Settings > Channels and sources** and click + **Create channel**. Select **Chat**, then choose **Slack** with the `Internal` + badge. Click **Next**. + -## Objects as workflow recipients + + If your project is already connected to Slack through the [Knock Slack + extension](/integrations/extensions/slack) with the required permissions, + Knock uses that connection to create the internal Slack channel. -To add channel data, we’ll set up an incoming webhook in Slack. To get this URL from Slack, you can go to “Incoming Webhooks” within your dashboard and toggle the "Activate Incoming Webhooks" feature. If you’ve already installed your app into a workspace, you will be asked to reinstall it and select a channel the app will post messages to. + If Slack is not connected, or if the existing connection needs additional + permissions, Knock opens the Slack authorization flow. Choose your workspace + and approve the requested permissions. After you return to Knock, the + internal Slack channel is created automatically. -activating incoming webhooks in Slack -To generate a new webhook, scroll to the bottom of the page where you see the “Add -New Webhook to Workspace” button. If you connected an initial channel, you can copy -your webhook, or you can connect another channel and then copy the webhook URL: - -creating a Slack channel in Knock dashboard + -### Set the webhook as channel data + + The channel configuration shows the Slack workspace managed by the Knock + Slack extension. Its credentials apply across your Knock environments and + cannot be edited from the channel configuration. -Now that you have the webhook URL, we’ll store that webhook as a special property on the repository Object called channel data. [Channel data is both channel and recipient-specific data](https://docs.knock.app/managing-recipients/setting-channel-data) stored for use with particular channels, like a token used for push notifications or webhooks stored for chat apps like Slack, Teams, and Discord. Both Users and Objects can store channel data. + You can create one internal Slack channel per Knock account. The same + channel can be reused across any number of workflows. -In the code example below, we’ll use the `knockClient.objects.setChannelData` method to update the channel data for our repository Object. + + -```javascript -import Knock from "@knocklabs/node"; -const knockClient = new Knock({ apiKey: process.env.KNOCK_API_KEY }); - -await knockClient.objects.setChannelData( - "repositories", - repository.id, - process.env.KNOCK_SLACK_CHANNEL_ID, - { - data: { - connections: [ - { - incoming_webhook: { url: "url-from-slack" }, - }, - ], - }, - }, -); -``` +## Add internal Slack messaging to a workflow -Here, you’ll also need your `KNOCK_SLACK_CHANNEL_ID` as the third parameter, which is the channel ID of your Slack integration within Knock, so that Knock can reference that channel when it processes workflows that use it. The last parameter is an object of a specific format that varies based on [the type of message provider](/managing-recipients/setting-channel-data#provider-data-requirements). In this case, it is a `SlackConnection` object with an `incoming_webhook` property that contains the URL you copied from Slack. + + + Open a workflow and add a chat app channel step. Select your internal Slack + channel. + -### Trigger a workflow with an object recipient + + Use the **Send to** field to search the connected workspace. Choose a + destination from either the **Channels** or **People** tab. -With the channel data in place, you can add Slack as a workflow step in any workflow. For this example, we’ll create a `new-issue` workflow that pings users in our connected Slack channel whenever someone adds a new issue. + The destination is stored on this workflow step. Other steps using the same + internal Slack channel can be configured to send elsewhere. -workflow with a Slack step + -As you create your message template, remember that in this case the repository Object is the recipient of your workflow. That means any properties you reference on your Liquid template tags need to exist as properties of the Object as well: + + Write the Slack message using Knock's markdown or Block Kit editor, then + commit the workflow. You do not need to configure a recipient connection in + the template settings; Knock supplies the Slack destination and credentials + for you. + + -```markdown -There was an issue opened on the following repo: **{{ recipient.name }}** -``` +## Trigger the workflow -Finally, we’ll add the workflow trigger to our code with the repository Object as a recipient. +Trigger a workflow that uses internal Slack messaging the same way you trigger any other Knock workflow. A recipient is still required for the workflow run, but that recipient does not need Slack channel data. -```javascript +```javascript title="Trigger a workflow that uses internal Slack messaging" import Knock from "@knocklabs/node"; + const knock = new Knock({ apiKey: process.env.KNOCK_API_KEY }); -await knock.workflows.trigger("new-issue", { - recipients: [{ collection: "repositories", id: "repo-1" }], +await knock.workflows.trigger("support-alert", { + recipients: ["user-1"], + data: { + summary: "A customer needs help with a failed import.", + }, }); ``` -With that, you should see a message in your selected Slack channel: +The workflow recipient still provides the `recipient` variables used in Liquid templates, step conditions, and the rest of the workflow. The destination selected in **Send to** only changes where that internal Slack step is delivered. -A Slack message +## How recipient preferences work + +Messages sent through internal Slack messaging bypass the workflow recipient's notification [preferences](/preferences/overview) because the message is delivered to a configured destination, not to a Slack connection owned by that recipient. Channel and step [conditions](/concepts/conditions) still evaluate normally against the workflow `recipient`, if set. + +Each internal Slack step sends exactly one message to its selected destination. In workflow runs and message details, **Delivered to** shows the Slack channel or person that received the message, while the recipient associated with the message remains the workflow `recipient`. + +## Manage or reconnect Slack + +The Knock Slack extension owns the workspace connection and credentials used by the internal Slack channel. Manage the connection from **Settings > Extensions**, not from the channel's provider settings. + +If the extension is disconnected or needs to be authorized again, Knock preserves the internal Slack channel and its workflow references but skips affected Slack steps until the workspace is reconnected. The workflow run log identifies the disconnected Slack connection as the reason. Open **Settings > Extensions** and reconnect Slack to resume delivery. + +## When to use a different Slack setup + +Use internal Slack messaging only when you want Knock to message your own team's workspace through the Knock Slack app. + +If you are building a customer-facing Slack integration, use [your own Slack app and SlackKit](/integrations/chat/slack/sending-a-message-to-channels). diff --git a/content/integrations/extensions/slack.mdx b/content/integrations/extensions/slack.mdx index 062eab723..d32b8c58b 100644 --- a/content/integrations/extensions/slack.mdx +++ b/content/integrations/extensions/slack.mdx @@ -1,12 +1,12 @@ --- title: Connecting Knock to your Slack workspace -description: Use the Knock Slack extension to launch Knock agents from your Slack workspace. +description: Use the Knock Slack extension to launch Knock agents and send workflow messages in your team's Slack workspace. layout: integrations tags: ["slack", "extensions"] section: Integrations > Extensions --- -The Knock Slack extension lets your team launch Knock agents directly in Slack to build, manage, and ship customer messaging. Users can DM the agent or tag `@Knock` in any channel to kick off an agent session. +The Knock Slack extension connects your team's Slack workspace to Knock. It lets your team launch Knock agents directly in Slack and powers [internal Slack messaging](/integrations/chat/slack/sending-an-internal-message) for sending workflow messages to channels and people in your workspace. ## Setting up the Knock Slack extension @@ -16,6 +16,8 @@ The Knock Slack extension lets your team launch Knock agents directly in Slack t 4. After installing, you'll be redirected to Knock to finalize the installation. 5. Prompt the Knock agent in a direct message or tag `@Knock` in any channel. +Connecting the extension does not create an internal Slack channel automatically. To use the connection for workflow messages, create an internal Slack channel from **Settings > Channels and sources**. + ## Authenticating users In order to use the Knock Slack extension, users will need to link their Slack user account to their Knock account. @@ -24,6 +26,12 @@ Users within your Slack workspace can authenticate by prompting the Knock agent ## Using the Knock Slack extension +### Sending workflow messages to Slack + +After connecting the extension, you can create one managed internal Slack channel for your Knock account. Workflow authors can use that Knock channel to select a Slack channel or person as the destination for each step, without managing a Slack app, bot token, or recipient channel data. + +See [Sending messages to your team's Slack workspace](/integrations/chat/slack/sending-an-internal-message) for setup and delivery behavior. + ### Kicking off an agent Users can kick off an agent session by prompting the Knock agent in a direct message or tagging `@Knock` in any channel. The agent will respond with a message indicating that it has started and will begin processing the user's request. @@ -56,19 +64,26 @@ In each agent session, you can click the "Open agent" button to view the full co ## Disconnecting Slack -Users can disconnect their linked Slack account from their user settings under "Settings > Profile > Overview" at any time. Once disconnected, they will no longer be able to use the Knock Slack extension. +Users can disconnect their linked Slack account from their user settings under **Settings > Profile > Overview** at any time. Once disconnected, they will no longer be able to use the Knock Slack extension as that user. + +An administrator can manage or disconnect the workspace extension from **Settings > Extensions**. Disconnecting the workspace stops agent sessions and internal Slack messaging. Any internal Slack channel and its workflow references are preserved so delivery can resume after the workspace is reconnected. ## Permissions Knock requests these Slack permissions for the Knock Slack extension to work within your workspace: -| Permission | Why we need it | -| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `app_mentions:read` | Lets the Knock agent respond when a user @mentions the app in a channel. This is the primary way users start a conversation with the agent in shared channels. | -| `assistant:write` | Powers the Slack Assistant experience: shows thread status (e.g. "Thinking…") while the agent runs, and uses Slack's Assistant thread APIs so responses feel native in Slack. | -| `chat:write` | Sends the agent's replies in Slack threads and DMs, including streamed responses (`chat.startStream` / `chat.appendStream` / `chat.stopStream`) and follow-up messages such as run summaries and account-linking prompts. | -| `channels:history` | Reads recent messages in public channel threads (via `conversations.replies`) so the agent has conversation context when a user continues a thread. Limited to the 25 most recent messages in that thread. | -| `groups:history` | Same as `channels:history`, but for private channels and group DMs (mpim), so thread context works outside public channels. | -| `im:history` | Reads recent messages in 1:1 DMs so the agent can follow an ongoing direct-message conversation. DMs don't emit `app_mention` events, so message history is needed for context on follow-ups. | -| `users:read` | Looks up Slack user display names when building thread transcripts, so prior messages are labeled with human-readable names instead of raw user IDs. | -| `files:read` | Downloads image files shared in a thread (when users attach screenshots or other images) so the agent can understand visual context in the conversation. Images are capped in size and count. | +| Permission | Why we need it | +| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `app_mentions:read` | Lets the Knock agent respond when a user @mentions the app in a channel. This is the primary way users start a conversation with the agent in shared channels. | +| `assistant:write` | Powers the Slack Assistant experience: shows thread status (e.g. "Thinking…") while the agent runs, and uses Slack's Assistant thread APIs so responses feel native in Slack. | +| `chat:write` | Sends agent replies and internal Slack workflow messages to conversations the Knock Slack app can access. | +| `chat:write.public` | Sends internal Slack workflow messages to public channels without requiring the Knock Slack app to be invited first. | +| `channels:read` | Lists public channels so workflow authors can choose an internal Slack destination. | +| `channels:history` | Reads recent messages in public channel threads (via `conversations.replies`) so the agent has conversation context when a user continues a thread. Limited to the 25 most recent messages in that thread. | +| `groups:read` | Lists private channels where the Knock Slack app is a member so workflow authors can choose them as internal Slack destinations. | +| `groups:history` | Same as `channels:history`, but for private channels and group DMs (multi-party instant messages), so thread context works outside public channels. | +| `im:history` | Reads recent messages in 1:1 DMs so the agent can follow an ongoing direct-message conversation. DMs don't emit `app_mention` events, so message history is needed for context on follow-ups. | +| `im:read` | Finds direct-message conversations used by the Knock agent. | +| `im:write` | Opens direct-message conversations for agent replies and internal Slack messages sent to a person. | +| `users:read` | Lists people for internal Slack destinations and looks up display names when building agent thread transcripts. | +| `files:read` | Downloads image files shared in a thread (when users attach screenshots or other images) so the agent can understand visual context in the conversation. Images are capped in size and count. | diff --git a/data/sidebars/integrationsSidebar.ts b/data/sidebars/integrationsSidebar.ts index 48e223f11..24531fe17 100644 --- a/data/sidebars/integrationsSidebar.ts +++ b/data/sidebars/integrationsSidebar.ts @@ -79,7 +79,7 @@ export const INTEGRATIONS_SIDEBAR: SidebarContent[] = [ { slug: "/overview", title: "Overview" }, { slug: "/sending-an-internal-message", - title: "Sending an internal message", + title: "Messaging your workspace", }, { slug: "/sending-a-direct-message",