Connect Slack

Register a Slack app for one Coworker, paste its credentials, install it in your workspace, choose how Slack reaches Workforce Intelligence, and decide whether it may answer in channels.

For: Administrators (the admin ability) · Last updated

A chat app lets people message one Coworker from Slack. Each app is bound to exactly one Coworker, so the Coworker has its own app name in Slack and people always know who they are talking to. To offer three Coworkers in Slack, add three apps. You create the Slack app yourself, in your own Slack workspace, from a manifest that Workforce Intelligence generates for you.

The Coworker answers with the permissions of the person who messaged it, never with more. See Chat with a Coworker in Slack or Microsoft Teams for what people see.

Before you start#

  • You need the admin ability. Chat apps is on Settings, in the Coworkers & Apps group, and appears while the Coworkers product area is on (see Features). Anyone else who opens the page sees "Managing chat apps requires the admin role."
  • You need permission to create and install apps in your Slack workspace.
  • Slack agents can require a paid Slack plan; check your plan.
  • Choose how Slack will reach Workforce Intelligence (next section). Both ways need Workforce Intelligence's public address to start with https:// (see Domains and HTTPS), because Slack sends people back to it after they approve the app.

Choose how Slack reaches Workforce Intelligence#

When you add the app you choose one of two ways:

Choice How it works Pick it when
Slack sends events to us Slack sends each message and button click to your deployment's public API address, /api/channels/slack/<app>/events and /interactivity. The address must start with https:// and be reachable from the internet. Your deployment already has a public address Slack can call.
We connect to Slack Your deployment opens one outbound connection to Slack and keeps it open (Slack calls this Socket Mode). Nothing needs to reach your deployment from outside. Your deployment is behind a firewall or has no public address. You also create an app-level token in Slack.

Each connection state is shown on the app card. With the socket choice the card shows Slack connection as Connected or Not connected. Only one process holds an app's connection at a time. Slack's own documentation does not say that agent apps receive their events over this connection, so after you connect, confirm with a direct message that the Coworker answers. If it does not, switch the app to Slack sends events to us.

With We connect to Slack, if the connection drops or the deployment restarts, the direct messages people sent in the meantime are not lost: when the connection returns, the Coworker answers the ones it missed, oldest first, as long as they are less than 24 hours old (at most 50 per conversation). A missed message sent at the top of a direct message starts a new thread, like a live one. This covers messages in direct messages only, not replies inside a thread and not mentions in channels, and it applies only to people who have already messaged the Coworker. It needs the im:history permission, which the manifest already includes.

Add the app#

  1. Open Settings > Chat apps and select Add chat app. (With no apps yet the page reads "No chat apps" and offers the same button.)
  2. Under Chat app, choose Slack.
  3. Choose the Coworker people will message. The app is listed here as, for example, "Ren - Slack", and appears in Slack under the Coworker's name ("Ren").
  4. Under How Slack reaches this deployment, choose one of the two options above.
  5. Select Add app.

The app appears on the page as Needs install with the guided setup open. The setup has five steps, and the first one that is not finished opens by itself.

Create the app in Slack#

Step 2, Create the app in Slack, always shows a short explanation ("Slack apps are created in Slack, from the manifest below. Open Slack's app page, create a new app from a manifest, paste the manifest, then come back and enter its App ID."), an Open Slack's app page button and a Read the full guide link, followed by the generated setup instructions and the manifest. If the manifest cannot be built, for example because the deployment's public address does not start with https://, the reason shows above the Redirect URL and App ID fields and the explanation stays on the page.

  1. Select Create app in Slack. Slack opens its create-from-manifest page with everything filled in. If the manifest is too long to open from a link, the page tells you to open your apps in Slack, choose Create New App, then From a manifest, pick your workspace and paste the manifest. Use Copy manifest to copy it.
  2. Create the app in your workspace.
  3. Open the new app's Basic Information page in Slack and copy its App ID. It starts with A.
  4. Back in Workforce Intelligence, paste it into App ID and select Save App ID.

The manifest sets the app name, a short description of the Coworker, the agent view, the Messages tab (so people can write to the app), the bot permissions, the events and the redirect address. The permissions it asks for are: app_mentions:read, assistant:write, channels:history, channels:read, chat:write, files:read, files:write, groups:history, groups:read, im:history, im:write, mpim:history, reactions:write and users:read. The three ...:history permissions (public channels, private channels and group direct messages) and users:read let the Coworker read the messages around a mention and show who wrote them; see Allow in channels. reactions:write lets the Coworker add a reaction to a message, channels:read and groups:read let it see which public and private channels it has been added to, and users:read also lets it look up people in your workspace by name. It subscribes to the events app_home_opened, app_mention, message.im and agent_session_stopped, turns on interactivity, and leaves token rotation off. Under Slack sends events to us it also includes the two request addresses, which the step lists as Events URL and Redirect URL with a copy button beside each.

Save the app's credentials#

Step 3, Save the app's credentials, takes the values from the app's Basic Information page in Slack:

Field Where it comes from
Client ID Under App Credentials.
Client secret Under App Credentials. Slack hides it until you choose Show.
Signing secret Under App Credentials. It lets Workforce Intelligence confirm that a message really came from Slack.
App-level token Only for We connect to Slack. Under Basic Information, App-Level Tokens, create one with the connections:write scope.

Select Save credentials. The values are stored encrypted and are never shown again: a saved field reads Saved, with a Replace button. You can save the values together or one at a time.

Install to Slack#

Step 4, Install to Slack, needs the App ID and the Client ID and Client secret saved first. If they are missing the step reads, for example, "Save the App ID and the client id and client secret first."

  1. Select Install to Slack. The button reads Opening Slack… while it works.
  2. In Slack, approve the permissions for your workspace.
  3. Slack returns you to Chat apps. A message reads "<app name> is installed. Send it a direct message in Slack to try it." and the card shows Installed. Step 4 then names the workspace ("installed in Slack workspace <name>"). The workspace name is also what people see on the link page; Test connection fills it in for an app installed before names were saved.

You must be signed in to Workforce Intelligence as an administrator when Slack returns you. The install link works once and expires after ten minutes. To approve new permissions or replace the saved bot token later, select Reinstall to Slack. The App ID cannot be changed once the app is installed.

If the install does not finish, the page shows one of these messages:

Message What it means and what to do
"The install was cancelled in Slack, so the app was not added. Choose Install to Slack and approve the permissions it asks for." Someone chose Cancel in Slack. Start again.
"The install link expired before it was used. Choose Install to Slack to get a new one." The link is older than ten minutes, or was already used.
"Slack installed a different app than the one saved here. Check that the App ID matches the app you are installing, then try again." The App ID saved here belongs to another Slack app.
"This app is already installed in a different Slack workspace. Delete this chat app and add it again to use another workspace." An app serves one workspace.
"Slack offered an install for a whole organization, which isn't supported. Install the app to a single workspace instead." Organization-wide installs are not supported.
"Slack didn't complete the install. Check the client id and client secret saved here, then try again." Slack refused the code exchange. Replace the Client ID and Client secret and retry.
"Sign in to Workforce Intelligence as an admin, then choose Install to Slack again." You were not signed in, or not as an administrator, when Slack returned you.

Before the install link can be made, the deployment's public address (WI_PUBLIC_BASE_URL) must start with https://, and under Slack sends events to us its API address (WI_API_BASE_URL) must too. The page names the address at fault. See Configuration reference.

Check the connection#

Step 5, Check the connection, shows Install (Installed or Needs install), Messages ("Ready to receive messages." or "Save the signing secret to receive messages."), and, for the socket choice, Connection to Slack. Select Test connection to ask Slack whether the saved bot token works. A pass reads "Connected to <workspace>." If the app was installed before the history and users:read permissions were added, the result adds "Reinstall the app to let the Coworker read the messages around a mention." The connection still works; only that reading is off until you update the app. A failure explains why, for example "Install the app to your Slack workspace first." or "The saved token belongs to a different Slack workspace." Then open Slack, find the app and send it a direct message.

Manage the app#

Select Manage on an app's card (or Continue setup while setup is unfinished). Under Settings:

  • Coworker, then Save changes. Changing the Coworker makes the app, renamed to match (change the name in Slack's app settings too), answer as that Coworker from then on; people's existing chats with the old Coworker are kept in Workforce Intelligence.
  • Turned on: when off, nobody can message the Coworker through this app, and nothing reaches Slack from it.
  • Allow in channels: see the next section.
  • Delete app asks you to confirm. The app stops answering, its saved credentials are removed and its chat threads are removed from Workforce Intelligence. Conversations already in Workforce Intelligence stay, people's linked Slack accounts stay, and you can add the app again at any time. Delete the app in Slack as well if you no longer want it there.

A card shows Provider, Coworker, Install, Connection, Status (On or Off) and Channels (Allowed or Direct messages only).

Allow in channels#

By default the Coworker answers only in direct messages. Turn on Allow in channels so people can mention it in Slack channels. Think about this before you turn it on: everyone in the channel sees the reply, while the Coworker uses only the permissions of the person who asked. A person with access to private information can therefore, by asking in a channel, show it to the whole channel. Direct messages are always on. In a direct message, each thread is its own conversation with that person and a new message at the top continues from their most recent one, the same way as in a channel. In channels the Coworker answers when it is mentioned. Each thread is its own conversation with that person; a new thread continues from that person's most recent conversation in the same channel, and a conversation is never shared with another person. A message sent while the Coworker is still working on the same person's request is added to that request. Turn the setting off again at any time.

When someone mentions the Coworker in a channel or thread, it reads what that person's conversation has not seen. The first time that person mentions it in the channel, that is the few messages just before the mention (up to 10, and no more than about 8,000 characters), so it understands what "what do you think?" refers to. A new thread of that person reads what was posted in the channel since they last talked to it: up to 30 messages (about 8,000 characters in all, oldest dropped first). A person who is new to a thread, for instance someone mentioning the Coworker in a thread that another person started, reads that thread from its first message (up to 30 messages, the first one always kept), including the Coworker's replies to the others; it never reads another person's conversation with the Coworker. When a person returns to their own thread, it reads that thread's messages since they last wrote there plus the thread's first message. Replies inside other threads of the channel are not read, because Slack's channel history leaves them out. The Coworker's own replies to that person are left out (the conversation already has them). It reads them only in channels the app has been added to, only when Allow in channels is on, and never in direct messages. It treats those messages as information from other people, not as instructions, and still acts only with the permissions of the person who mentioned it. Their text is kept with that person's conversation in Workforce Intelligence and is deleted with it. Reading names uses users:read; without it the Coworker shows Slack user ids instead.

Apps installed before a permission was added#

Slack does not add permissions to an installed app by itself. For an existing app: in Slack, open the app's App Manifest and add the missing bot scopes (channels:history, groups:history, mpim:history, users:read, reactions:write, channels:read and groups:read), or copy the new manifest from Create the app in Slack, then in Chat apps select Reinstall to Slack and approve. Until then the Coworker still answers mentions, just without the surrounding messages, without reacting to messages and without finding channels, and Test connection says so: "Reinstall the app to let the Coworker react and find channels."

What the Coworker can do on its own#

Besides answering, a Coworker can post and message when a person asks it to (or when a schedule that person set up runs): it can post in channels it was added to, send a direct message to a member of your workspace, add a reaction and read a thread it took part in. This needs the chat:write, im:write, users:read, channels:read, groups:read and reactions:write permissions, and the three ...:history permissions to read a thread. im:write opens a direct message with a workspace member, and users:read finds members by name. Every one of these actions acts for the person the run is for, uses the same app and goes through the same limits: 20 messages and 30 reactions in one run, 60 messages and 200 reactions per Coworker per hour, and 10 messages to one destination per hour. The Coworker posts only where it was invited; it never sends @channel, @here or other mass mentions, and never messages another bot. A person it messages who has not linked their account gets the usual Link account prompt if they reply. Nothing else is needed in settings: there is no separate switch.

A trigger can also have a default destination: a channel the app has been invited to, or a direct message to the person who created the trigger. When a run finishes, its final message is posted there automatically, as that person (no separate switch, no list of allowed channels), and a script's message to "default" goes to the same place. The destination list shows the channels the app is a member of, read from Slack when the list is opened. Choosing, changing or clearing it is recorded in the Audit tab as Changed where a trigger posts its results, with the channel name and never Slack's own channel identifier. Deleting the app clears every destination that used it. See Triggers.

An app installed before these permissions were added keeps working for everything it did, and tells the person "The app needs a quick reinstall to do this" for the new actions. Select Reinstall to Slack (see Install to Slack above) and approve to grant them.

What people see#

  • A person who has not linked their account gets a private direct message with a Link account button. See Chat with a Coworker in Slack or Microsoft Teams.
  • Replies longer than Slack's message limit are split into several messages. A file the Coworker shares or creates, including one it shared earlier in the same request, is uploaded to the conversation after its reply (at most 10 per reply), or posted as a link to the file in Workforce Intelligence if the upload fails.
  • Files people send can be of any type, up to 10 files per message and 10 MB each. Each one is saved in the person's conversation (and follows the company's file retention setting) and is placed in the Coworker's working folder, so the Coworker can open and work with it. The Coworker sees images directly. A file that cannot be placed in the working folder is still saved in the conversation, and the Coworker is told it is unavailable. A message longer than 32,000 characters is refused with a request to shorten it.
  • When someone who may not answer an approval request selects Approve or Deny in a channel or thread, the answer ("This request is no longer available." and the like) appears only for them, in place, and nothing is posted to the rest of the channel.
  • If something goes wrong while the Coworker is answering, it says so in one short sentence and invites the person to send the message again.

Everything people do through the app follows the Coworker's normal access rules. A person who may not chat with the Coworker is told "You don't have access to chat with me. Ask your administrator." A person who was revoked or disabled gets no answer.

Who can do what#

Adding, changing, installing, turning on and off, and deleting a chat app needs the admin ability, and the Coworkers product area must be on. People cannot see the app's credentials: they are write-only. Every change is recorded in the audit log as Added a chat app, Changed a chat app, Removed a chat app or Replaced a chat app's credentials, with the app's name and the names of the fields that changed, never a secret. See The Audit log.

Reaching Slack#

Your deployment sends replies to Slack over HTTPS, and with Socket Mode it also keeps an outbound connection open to Slack. If a firewall limits outbound traffic, allow slack.com and its subdomains on port 443. See Deployment requirements.