From dd1f0ff2462292b03964d0eb28a6b9ac360f38a8 Mon Sep 17 00:00:00 2001 From: Meryl Dakin Date: Wed, 12 Aug 2026 10:36:09 -0400 Subject: [PATCH 1/3] docs: document Internal Slack channels --- content/integrations/chat/slack/overview.mdx | 18 +- .../slack/sending-an-internal-message.mdx | 180 +++++++++--------- content/integrations/extensions/slack.mdx | 41 ++-- data/sidebars/integrationsSidebar.ts | 2 +- 4 files changed, 136 insertions(+), 105 deletions(-) diff --git a/content/integrations/chat/slack/overview.mdx b/content/integrations/chat/slack/overview.mdx index 09bc3d657..842517bef 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: + +- [Send messages to your team's Slack workspace](/integrations/chat/slack/sending-an-internal-message) using a managed Internal Slack channel. +- [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..64541ef19 100644 --- a/content/integrations/chat/slack/sending-an-internal-message.mdx +++ b/content/integrations/chat/slack/sending-an-internal-message.mdx @@ -1,120 +1,128 @@ --- -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 an Internal Slack channel 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. +Knock's Internal Slack channel 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 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. + -## 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 project. 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 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 channel step using 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 send somewhere else. -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 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 sends to Internal Slack" 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 + +Internal Slack sends bypass the workflow recipient's notification preferences because the message is going to a team destination, not to a Slack connection owned by that recipient. Channel and step conditions still evaluate normally against the workflow recipient. + +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 message's recipient 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 an Internal Slack channel 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). If you need to supply a custom bot token, incoming webhook, or Liquid-based destination, use a customer-configured Slack channel with a [recipient connection override](/integrations/chat/slack/overriding-recipient-connections). diff --git a/content/integrations/extensions/slack.mdx b/content/integrations/extensions/slack.mdx index 062eab723..66e6f0871 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 channels](/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 project. 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 delivery. 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 (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. | +| `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..8124ae50a 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 Slack workspace", }, { slug: "/sending-a-direct-message", From 24134a7800dea540f9f02b866fb5290aebdc76d3 Mon Sep 17 00:00:00 2001 From: Meryl Dakin Date: Thu, 13 Aug 2026 08:38:50 -0400 Subject: [PATCH 2/3] docs: address Internal Slack review feedback --- content/integrations/chat/slack/overview.mdx | 4 +- .../slack/sending-an-internal-message.mdx | 57 ++++++++++--------- content/integrations/extensions/slack.mdx | 24 ++++---- data/sidebars/integrationsSidebar.ts | 2 +- 4 files changed, 44 insertions(+), 43 deletions(-) diff --git a/content/integrations/chat/slack/overview.mdx b/content/integrations/chat/slack/overview.mdx index 842517bef..b679e1d51 100644 --- a/content/integrations/chat/slack/overview.mdx +++ b/content/integrations/chat/slack/overview.mdx @@ -11,7 +11,7 @@ This page covers how to use Knock to send notifications to Slack. You can use Kn Knock's Slack integration enables you to: -- [Send messages to your team's Slack workspace](/integrations/chat/slack/sending-an-internal-message) using a managed Internal Slack channel. +- [Send messages to your team's Slack workspace](/integrations/chat/slack/sending-an-internal-message) using a managed internal Slack channel. - [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. @@ -21,7 +21,7 @@ This integration does not support Slack modals, slash commands, shortcuts, or in ## 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. +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 multiple ways to connect your own Slack app depending on your technical requirements: diff --git a/content/integrations/chat/slack/sending-an-internal-message.mdx b/content/integrations/chat/slack/sending-an-internal-message.mdx index 64541ef19..c72817d4d 100644 --- a/content/integrations/chat/slack/sending-an-internal-message.mdx +++ b/content/integrations/chat/slack/sending-an-internal-message.mdx @@ -1,12 +1,12 @@ --- title: Sending messages to your team's Slack workspace -description: Use an Internal Slack channel to send Knock workflow messages to channels and people in your team's Slack workspace. +description: Use an internal Slack channel to send Knock workflow messages to channels and people in your team's Slack workspace. tags: ["slack", "chat"] section: Integrations > Slack layout: integrations --- -Knock's Internal Slack channel 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. +Knock's internal Slack channel 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. @@ -15,18 +15,18 @@ You don't need to create a Slack app, manage bot tokens, or store Slack `channel title="Knock channels and Slack destinations are different." text={ <> - 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. + 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. } /> ## Before you begin -To create an Internal Slack channel, you need a Knock role 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. +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. The Knock Slack app can send to: @@ -34,24 +34,24 @@ The Knock Slack app can send to: - 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. -## Create an Internal Slack channel +## Create an internal Slack channel - - In the Knock dashboard, open **Settings > Channels and sources** and click - **Create channel**. Select **Chat**, then choose **Slack** with the - **Internal** badge. + + In the Knock dashboard, open **Settings > Channels and sources** and click + **Create channel**. Select **Chat**, then choose **Slack** with the `Internal` + badge. Click **Next**. 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. + Knock uses that connection to create the internal Slack channel. 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. + internal Slack channel is created automatically. @@ -60,17 +60,18 @@ The Knock Slack app can send to: Slack extension. Its credentials apply across your Knock environments and cannot be edited from the channel configuration. - You can create one Internal Slack channel per Knock project. The same + You can create one internal Slack channel per Knock account. The same channel can be reused across any number of workflows. -## Add Internal Slack to a workflow +## Add internal Slack to a workflow - Open a workflow and add a channel step using your Internal Slack channel. + Open a workflow and add a chat app channel step. Select your internal Slack + channel. @@ -78,7 +79,7 @@ The Knock Slack app can send to: destination from either the **Channels** or **People** tab. The destination is stored on this workflow step. Other steps using the same - Internal Slack channel can send somewhere else. + internal Slack channel can be configured to send elsewhere. @@ -92,9 +93,9 @@ The Knock Slack app can send to: ## Trigger the workflow -Trigger a workflow that uses Internal Slack 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. +Trigger a workflow that uses internal Slack 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 title="Trigger a workflow that sends to Internal Slack" +```javascript title="Trigger a workflow that sends to internal Slack" import Knock from "@knocklabs/node"; const knock = new Knock({ apiKey: process.env.KNOCK_API_KEY }); @@ -107,22 +108,22 @@ await knock.workflows.trigger("support-alert", { }); ``` -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. +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. ## How recipient preferences work -Internal Slack sends bypass the workflow recipient's notification preferences because the message is going to a team destination, not to a Slack connection owned by that recipient. Channel and step conditions still evaluate normally against the workflow recipient. +Internal Slack sends 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 message's recipient remains the workflow recipient. +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. +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. +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 an Internal Slack channel when you want Knock to message your own team's workspace through the Knock Slack app. +An internal Slack channel should only be used 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). If you need to supply a custom bot token, incoming webhook, or Liquid-based destination, use a customer-configured Slack channel with a [recipient connection override](/integrations/chat/slack/overriding-recipient-connections). +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 66e6f0871..3e671c0ab 100644 --- a/content/integrations/extensions/slack.mdx +++ b/content/integrations/extensions/slack.mdx @@ -6,7 +6,7 @@ tags: ["slack", "extensions"] section: Integrations > Extensions --- -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 channels](/integrations/chat/slack/sending-an-internal-message) for sending workflow messages to channels and people in your workspace. +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 channels](/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,7 +16,7 @@ The Knock Slack extension connects your team's Slack workspace to Knock. It lets 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**. +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 @@ -28,7 +28,7 @@ Users within your Slack workspace can authenticate by prompting the Knock agent ### Sending workflow messages to Slack -After connecting the extension, you can create one managed Internal Slack channel for your Knock project. 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. +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. @@ -64,9 +64,9 @@ 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 as that user. +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 delivery. Any Internal Slack channel and its workflow references are preserved so delivery can resume after the workspace is reconnected. +An administrator can manage or disconnect the workspace extension from **Settings > Extensions**. Disconnecting the workspace stops agent sessions and internal Slack delivery. Any internal Slack channel and its workflow references are preserved so delivery can resume after the workspace is reconnected. ## Permissions @@ -76,14 +76,14 @@ Knock requests these Slack permissions for the Knock Slack extension to work wit | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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. | +| `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 (mpim), so thread context works outside public channels. | +| `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. | +| `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 8124ae50a..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: "Messaging your Slack workspace", + title: "Messaging your workspace", }, { slug: "/sending-a-direct-message", From 468925d8ae6d0ad3d15d415c172f1458f011461d Mon Sep 17 00:00:00 2001 From: Meryl Dakin Date: Thu, 13 Aug 2026 10:29:59 -0400 Subject: [PATCH 3/3] docs: name internal Slack messaging --- content/integrations/chat/slack/overview.mdx | 2 +- .../chat/slack/sending-an-internal-message.mdx | 14 +++++++------- content/integrations/extensions/slack.mdx | 4 ++-- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/content/integrations/chat/slack/overview.mdx b/content/integrations/chat/slack/overview.mdx index b679e1d51..0105d7097 100644 --- a/content/integrations/chat/slack/overview.mdx +++ b/content/integrations/chat/slack/overview.mdx @@ -11,7 +11,7 @@ This page covers how to use Knock to send notifications to Slack. You can use Kn Knock's Slack integration enables you to: -- [Send messages to your team's Slack workspace](/integrations/chat/slack/sending-an-internal-message) using a managed internal Slack channel. +- 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. diff --git a/content/integrations/chat/slack/sending-an-internal-message.mdx b/content/integrations/chat/slack/sending-an-internal-message.mdx index c72817d4d..0aed6f8af 100644 --- a/content/integrations/chat/slack/sending-an-internal-message.mdx +++ b/content/integrations/chat/slack/sending-an-internal-message.mdx @@ -1,12 +1,12 @@ --- title: Sending messages to your team's Slack workspace -description: Use an internal Slack channel to send Knock workflow messages to channels and people in 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 --- -Knock's internal Slack channel 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. +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. @@ -66,7 +66,7 @@ The Knock Slack app can send to: -## Add internal Slack to a workflow +## Add internal Slack messaging to a workflow @@ -93,9 +93,9 @@ The Knock Slack app can send to: ## Trigger the workflow -Trigger a workflow that uses internal Slack 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. +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 title="Trigger a workflow that sends to internal Slack" +```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 }); @@ -112,7 +112,7 @@ The workflow recipient still provides the `recipient` variables used in Liquid t ## How recipient preferences work -Internal Slack sends 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. +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`. @@ -124,6 +124,6 @@ If the extension is disconnected or needs to be authorized again, Knock preserve ## When to use a different Slack setup -An internal Slack channel should only be used when you want Knock to message your own team's workspace through the Knock Slack app. +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 3e671c0ab..d32b8c58b 100644 --- a/content/integrations/extensions/slack.mdx +++ b/content/integrations/extensions/slack.mdx @@ -6,7 +6,7 @@ tags: ["slack", "extensions"] section: Integrations > Extensions --- -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 channels](/integrations/chat/slack/sending-an-internal-message) for sending workflow messages to channels and people in your workspace. +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 @@ -66,7 +66,7 @@ In each agent session, you can click the "Open agent" button to view the full co 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 delivery. Any internal Slack channel and its workflow references are preserved so delivery can resume after the workspace is reconnected. +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