> ## Documentation Index
> Fetch the complete documentation index at: https://user-docs.olyrosstudios.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Slack integration

> Connect your Slack workspace and give each agent its own Slack app, or put one shared app in front of many agents.

A company connects one Slack workspace, then gives an agent its own Slack app, or puts one
[router](https://user-docs.olyrosstudios.com/routers.md) app in front of many agents, so people can talk to agents in channels,
threads and direct messages. The integration also keeps the Slack directory that agent and
workflow access lists draw on, links Slack people to Olyros users for cost attribution, and
queues every outbound message so long or interrupted replies arrive intact. Settings live on
each agent's **Slack** tab (`/agents/:agentId/slack`) or a router's (`/routers/:agentId/slack`),
in the sidebar group **Settings** under **Slack Users** (`/settings/slack-users`) and **Slack
Groups** (`/settings/slack-groups`, `/settings/slack-groups/:groupId`), and the workspace
connection under **Settings -> Integrations** (`/integrations`). Who may talk to an agent is set
on its **Access** tab (`/agents/:agentId/access`), described in [Agents](https://user-docs.olyrosstudios.com/agents.md).

## What it does

* **Workspace connection.** A company saves Slack *app configuration* tokens
  (`saveSlackConfigTokens`, `testSlackConfigTokens`); with them Olyros can create
  apps programmatically. `disconnectSlackWorkspace` removes the workspace and clears the
  stored Slack team, so the company can later connect a different workspace.
* **One Slack app per agent or router.** `POST /api/slack/agents/{agent_id}/create-app`
  builds the app from a manifest and installs it through Slack OAuth
  (`GET /api/slack/oauth/callback`); `.../reinstall` re-applies the manifest, and
  `upgradeSlackAppHomeManifests` upgrades pending App Home manifests (all, or one agent).
  The install link carries a signed state that expires after 600 seconds and is checked
  before Olyros talks to Slack: the person who started it must still be a company member,
  and an install into a different Slack team than the connected workspace is refused
  ("This Slack app was installed into a different Slack workspace than the one connected
  to this company."). An expired link shows "This Slack link expired. Open the agent's
  Slack page and click Re-authorize." The `AgentSlackConnection` holds the app id, bot
  user, encrypted bot credentials, display name and the channel list
  (`updateAgentSlackConnection`). `disconnectAgentFromSlack` detaches the app;
  `slackCapableAgents` lists agents eligible for Slack.
* **Routers.** A router is an agent of kind `router` with its own Slack app; it hands each
  person to the agent their route names, and replies, App Home buttons, questions and the
  busy prompt leave through the router's bot (`via_agent_id` records the path). One app
  can therefore front many agents and sandboxes. Routes and defaults are documented in
  [Routers](https://user-docs.olyrosstudios.com/routers.md), not here.
* **Channel list.** A non-empty channel list limits the channels the bot answers in: a
  mention in any other channel gets the ephemeral reply "I'm not enabled in this
  channel." and is not processed. Direct messages are not limited by the channel list;
  the agent's access list decides them. An empty list means every channel the bot is in.
  Channel ids must be Slack channel ids (`C…` or `G…`). The bot answers mentions only:
  `trigger_mode` accepts only `mentions_only`, and `all_messages` is rejected.
* **Conversations.** Slack events (`POST /api/slack/events`) and interactive actions
  (`POST /api/slack/interactions`) are signature-checked and mapped to the company from
  the verified workspace before any handler runs, acknowledged within Slack's budget and
  handled in the background; bot messages are ignored. Replies post as the agent's own bot (or the router's) and
  are threaded. Per agent, `setSlackReplyOptions` chooses a reply preset
  (`final_replies_only`, `status_and_replies`, `verbose`) or individual frames
  (`container_notice`, `session_metadata`, `thinking`, `tool_call_summary`,
  `tool_call_arguments`, `tool_call_result`, `error_detail`, `invocation_metrics`) and a
  rich-rendering preset (`plain`, `standard`, `rich`; toggles `final_reply_tables`,
  `final_reply_markdown`).
* **Outbound queue.** Every message goes through `SlackOutboundMessage` (`pending`
  with retries, attempts and `next_retry_at`; long replies are split into chunks with
  `chunk_sequence` / `chunk_total`; files attached by id). A platform admin can inspect
  and requeue (`/api/admin/slack-outbound/...`, admin app `/slack-outbound`). A second
  message sent while the agent is still busy is not dropped: the person gets an
  ephemeral prompt with **Wait** or **Stop & send**, and the pending message moves
  through `awaiting_decision`, `queued_for_after`, `dispatched` or `expired`.
* **Sandbox agents from Slack.** App Home and message buttons drive sandbox lifecycle
  actions `start`, `stop`, `rebuild`, `open_in_olyros`, `invocation_stop` and
  rebuild confirmations; each click is logged with result `ok`,
  `rejected_unauthorized`, `rejected_state` or `error`.
* **Questions to people.** When an agent asks a structured question
  (`olyros_ask_user`), it can be delivered as a Slack card; the click resumes the agent.
  Delivery channels are `web_chat`, `slack`, `text`.
* **Slack users.** The workspace user list is cached (`SlackUserCache`: names, email,
  avatar, bot flag, last activity) and refreshed per agent
  (`refreshSlackWorkspaceUsers`) or registered by email (`registerSlackUserByEmail`).
  A cached person is linked to an Olyros user automatically when the Slack profile is
  trusted (home team of the installation, not a guest, email confirmed) and its email
  matches a verified Olyros email.
  Admins browse and export it (`slackUsersPage` with search, linked filter and tags;
  `slackUsersActivityExport`), link a Slack person to an Olyros user (`linkSlackUser`,
  `unlinkSlackUser`), tag them for cost attribution (`setSlackUserTags`) and delete
  stale entries.
* **Slack groups and access.** Groups (`createSlackUserGroup`, add and remove members,
  `addTaggedSlackUsersToGroup` to build a group from a tag; origin `manual` or `tag`,
  with an optional Slack usergroup id) are subjects of access grants. An agent's Access
  tab (`setAgentAccess`) and a workflow's Access table can list Olyros users, Slack users
  and Slack groups; an object with no grant is open to everyone, one with any grant only
  to the listed subjects, on the web and in Slack alike (see [Agents](https://user-docs.olyrosstudios.com/agents.md)). A Slack
  user also passes through
  the Olyros user it is linked to. `deleteSlackUserGroup` refuses a group that any agent
  or workflow still grants, naming them. Admins audit who can reach which agent
  (`slackAccessAuditAgents`, `slackAccessAudit`); `agentSlackStats` shows per-agent Slack
  usage. The pickers show only people from the currently connected workspace
  (`slackUsersPage(currentWorkspaceOnly)`); the Slack Users page shows every cached row.
* **Workflows.** The `slack_message` node posts to a channel or user as a chosen
  agent; see [Workflows](https://user-docs.olyrosstudios.com/workflows.md).

## Who can use it

| Action | Role |
| - | - |
| Create or reinstall an agent's or router's Slack app (`POST /api/slack/agents/{agent_id}/create-app`, `.../reinstall`) | editor or admin, ability `integration.manage` (a viewer gets HTTP 403 `EDITOR_REQUIRED`, shown as "Only editors and admins can connect or re-authorize a Slack app.") |
| Channel list (`updateAgentSlackConnection`) | editor or admin, ability `integration.manage` (a viewer gets the GraphQL error "Editor or admin role required." in an HTTP 200 response) |
| Who may talk to an agent (`setAgentAccess`, Access tab) | editor or admin, ability `agent.manage` |
| Workspace tokens, reply options, refresh users, register by email, disconnect the workspace or an agent's app, list groups | any company member |
| Browse, export, link, tag or delete Slack users; create, edit and delete groups; access audit; App Home manifest upgrade; Slack user cost tags | company admin, ability `slack.manage` |
| Inspect and requeue the outbound queue | platform admin |

Talking to an agent in Slack is decided per agent by its Access table (ability
`agent.chat`), not by role. The abilities and their roles are listed under **Settings ->
Roles** (`/settings/roles`). No plan or tier gate.

## How to configure it

1. Settings -> Integrations -> Slack: paste the app configuration access and refresh
   tokens from Slack's app settings (`saveSlackConfigTokens`) and test them.
2. On an agent's Slack tab (`/agents/:agentId/slack`), **Create app**
   (`POST /api/slack/agents/{agent_id}/create-app`) and approve the install in Slack within
   ten minutes; then optionally list the channels it may answer in
   (`updateAgentSlackConnection`) and choose the reply and rich presets
   (`setSlackReplyOptions`). To serve many agents through one app, create a router under
   **Agents -> Routers** (`/routers`) and do this on the router's Slack tab instead
   ([Routers](https://user-docs.olyrosstudios.com/routers.md)).
3. Invite the bot to the channels you listed.
4. Settings -> Slack Users (`/settings/slack-users`): refresh the directory, link people
   to Olyros users, tag them; Settings -> Slack Groups (`/settings/slack-groups`): build
   groups.
5. On the agent's Access tab (`/agents/:agentId/access`, `setAgentAccess`) list the Olyros
   users, Slack users or Slack groups who may talk to it, then review the access audit.
6. After a manifest change, run the App Home upgrade (`upgradeSlackAppHomeManifests`).

## Limits and defaults

| Setting | Default | Where enforced |
| - | - | - |
| `trigger_mode` | `mentions_only`, the only accepted value | `updateAgentSlackConnection` validation |
| Channels | none listed = every channel the bot is in; DMs not limited by it | the agent's Slack connection channel list |
| Install link lifetime | 600 seconds, single company, initiator re-checked | signed install state |
| Workspaces per company | one at a time | `SlackWorkspaceConnection` |
| Reply preset / rich preset | per agent, stored in `slack_reply_options` | reply frame filter and renderer |
| Message length limits | per-frame limits with platform overrides (1 to 1,000,000 characters), cached 60 s | Slack delivery limits |
| Outbound retries | `attempts` and `next_retry_at` per message | outbound queue |
| Interactive ack budget | handled inline, work deferred to background | events and actions handlers |

## What it emits

* Agent conversations and tool activity rendered in Slack threads, per the reply
  options.
* Outbound message rows (status, attempts, chunks, posted timestamps) and pending
  message rows; processed-event records for dedup.
* Lifecycle action logs for sandbox buttons; HITL requests and answers.
* Slack user and group tables used by access control and cost attribution.

## Known gaps

* Everything is per workspace; a company cannot connect two Slack workspaces at once.
* The bot cannot listen to every message in a channel; there is no all-messages mode and
  only mentions and DMs reach the agent.
* Access audit and user management are admin-only and app creation needs an editor, but
  the workspace tokens and disconnecting a workspace or an agent's app are open to any
  member.
* There is no Slack *trigger node* for workflows; Slack starts agents, and agents can
  start workflows through the `api_trigger` tools.
* Automatic linking needs a matching verified email; there is no matching by SSO
  identity, and guests or Slack Connect users are never linked automatically.

## Customer-safe summary

Connect your Slack workspace and give each agent its own Slack app, or put one shared app
in front of many agents. People mention the agent in the channels you choose, or message
it directly, and it answers in a thread. You
decide how much it shows while working, from final answers only to full progress and tool
activity, and how richly it formats results. Long answers arrive in order, and if you message an agent that is still working you
can choose to wait or to interrupt it. Admins see who in Slack
is using which agent, group people, restrict agents to the right users, and attribute
usage to the people and teams behind it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.