#Slack integration

The Slack integration provides two independent connection types:

• A Slack workspace connection installs Sharkly's shared Slack app so people can create Tasks from Slack, post Task linkbacks, and preview Sharkly Task links.
• An Agent bot binding creates and installs a Slack app for one Sharkly Agent so messages can become Agent conversations.

Connecting a Slack workspace does not create Agent bot bindings, and connecting an Agent bot does not enable the Slack workspace Task features.

#Connect a Slack workspace

Organization Owners and Admins can open Integrations → Slack and select Connect under Connected Slack workspaces. Complete the Slack OAuth installation in the window that opens.

A Slack workspace can be connected to only one Sharkly Organization at a time. After connection, the shared app supports:

• creating a Task from a Slack slash command, global shortcut, or message shortcut;
• posting a thread reply with a Task link when a Task ID is mentioned, when Linkbacks is enabled;
• showing an expanded Task preview when a Sharkly Task link is shared, when Unfurls is enabled.

The Task creation flow lets the Slack user choose accessible Sharkly task fields such as Space, task type, and status. Access is resolved from the Slack user's identity and Sharkly Organization membership. Images, videos, and other selected attachments can be carried into the Task body and viewed in the Task.

#Update a Task from Slack

From a Slack Task card or detail panel, a member can update status, priority, assignee, labels, start date, and due date. Changes sync back to Sharkly, subject to the fields and actions allowed for that member's current identity.

Disconnecting the Slack workspace stops Task creation, linkbacks, link previews, and member notifications from that Slack workspace. It does not delete existing Sharkly Tasks or Slack messages.

#Slack notifications

Slack notifications are an optional delivery channel for Inbox events. Both of these must be in place before a member receives a Slack DM:

1. The organization has a connected Slack workspace.
2. The member has connected their personal Slack account.

Connect a personal Slack account from Settings → Notifications → Slack, from Settings → Connected accounts, or from My Slack account on the Slack integration page.

After a successful personal connection, Sharkly turns the Slack channel on automatically and sends a confirmation DM. That DM is the signal that the path works.

You can mute these groups independently:

• Assignments
• Status changes
• Comments and replies
• Mentions
• Agent activity

Muting a group stops Slack DMs for that group only. The Inbox still records the events. Muting the matching Inbox group stops both surfaces.

The channel delivers only events created after it is enabled. It does not replay the existing Inbox backlog. Personal Slack connections are organization-scoped; connect again in each organization where you want Slack DMs.

A status-change DM names the task ID, the previous and current statuses, and the actor. The task ID is a link; the current status is bold; the arrow is →. For example:

Task ENG-12082 status changed: Todo → In Progress, by Zero

#Task-bound Slack threads

When an Agent creates a Task from Slack, you can bind the current thread at the same time. After it is bound, task comments and thread messages stay in sync. Which comments go out follows the product UI.

Task detail shows the bound thread (for example, thread connected in {{channel}}). You can stop sync from there. Stopping sync does not delete the Task or the Slack history.

Status changes can also post to a bound thread. That is a separate notification from comment sync.

The thread message is not the same template as the Inbox DM above.

#Connect Slack in an automation workflow

Slack actions in an automation workflow (for example, sending a message) use a separate connection from the organization workspace and Agent bot bindings. Do not confuse this with Space automations that run on a schedule, status change, comment keyword, or webhook.

When you connect a Slack action, authentication options appear in this order:

If the deployment is self-hosted or has no platform Slack credentials, OAuth2 (Recommended) is hidden. It is not a switch that fails after you click it.

Slack is available in workflows as an action in this release. Slack triggers through the Events API are not wired yet, so do not treat Slack events as a workflow start.

The workflow connection and the organization Slack integration share the same Slack app. In the same workspace, both sides receive the same bot token; uninstalling or revoking one side affects the other. Workflow connections are Space-scoped resources and are not limited by the “one Slack workspace per organization” rule.

#Connect an Agent bot

An Agent bot connects one Sharkly Agent to one Slack app. Messages received by the bot become an Agent conversation, and the Agent's text reply returns to the same direct message or thread.

Agent bot conversations do not automatically create Tasks. If a conversation produces work that needs an owner, status, due date, or acceptance criteria, create a Task in Sharkly separately.

#Requirements

Before connecting Slack, prepare:

• An Agent you are allowed to use and configure in Sharkly
• Permission to generate a Slack App Configuration Token and install an app for the selected Slack team
• The Refresh Token from the Slack App Configuration Token

Each bot binds to one Agent, and an Agent can have only one Slack bot binding at a time. Your own Personal Agents and Space-shared Agents you can access can be selected; another person's Personal Agent cannot be selected.

#Get an App Configuration Refresh Token

1. Open https://api.slack.com/apps.
2. Open Your App Configuration Tokens.
3. Generate an App Configuration Token.
4. Copy its Refresh Token.

Treat this token as a secret. Submit it only through the Slack connection form.

#Connect a Slack bot

1. Open Integrations and select Slack.
2. Select Connect Agent.
3. Choose the Agent to bind.
4. Optionally enter an app name. If left blank, the Agent name is used. Slack app names are limited to 35 characters.
5. Paste the App Configuration Refresh Token.
6. Select Create & Install.
7. Complete the Slack OAuth authorization in the window that opens.
8. Return to Sharkly and wait for the bot status to change from Installing to Connected.

Sharkly exchanges the refresh token for a short-lived configuration access token, creates the Slack app from a manifest, and opens Slack for installation. The manifest configures the bot identity, writable App Home Messages tab, Slack Assistant view, OAuth redirect, Events API callback, event subscriptions, and required bot scopes.

After installation, Sharkly makes a best-effort attempt to send the installing user a greeting direct message. A greeting failure does not make the integration fail.

#Direct messages

Send a direct message to the installed bot to start a conversation with the bound Agent. The first message creates a Sharkly chat session for that Slack direct-message channel. Later messages in the same conversation continue that session.

Agent replies are sent back as text. Messages posted by bots or apps, edited-message events, join events, and other non-plain message events are ignored to prevent unwanted runs and reply loops.

#Channel mentions

Mention the bot in a public or private channel to start an Agent conversation:

@YourBot summarize the decision and list the next steps

Sharkly removes the leading mention, sends the remaining text to the Agent, and posts the reply in a thread rooted at the mention. By default, ordinary top-level channel messages do not trigger the Agent.

#Optional channel triggers

In the Agent's Slack integration, each trigger is a row that can be turned on or off. Hover to show Configure. Names follow the product UI. Typical options:

• Mentioned in a channel (default)
• Emoji reaction in a channel
• Any channel message (you must pick channels; it cannot apply to every channel)

An Any channel message trigger starts the Agent on ordinary messages in those channels without a mention. Other apps in the channel can also trigger it. An additional thread option controls whether messages in channel threads can also trigger it.

Emoji reaction: in a channel, reacting to a top-level message opens a new thread for the reply and includes nearby context; reacting inside a thread replies in that thread. Choose the trigger emoji in settings.

Use these settings only in channels where participants expect messages to be sent to the Agent. Keep mention-only behavior when broad automatic triggering would create noise or expose unrelated conversation context.

#Continue in a thread

After the Agent has joined a channel thread, users can continue replying in that thread without mentioning the bot again. With the default mention behavior, Sharkly continues threads that already have a matching Agent session. If the Any channel message thread option is enabled, other eligible thread replies in the configured channel can also start the Agent.

Each channel thread is isolated as its own Agent conversation. Replies return to the same channel and thread.

#Slack Assistant behavior

The generated Slack app enables Slack Assistant and subscribes to the events needed for Assistant messages. Assistant conversations use thread-aware chat sessions, so replies stay in the Assistant thread.

While the Agent is running, Sharkly attempts to show Thinking… through Slack's Assistant status API whenever the message has a thread anchor. This applies to Assistant conversations and channel mention threads. A plain direct message without a thread anchor does not receive this status, but the Agent still replies normally.

#Manage or disconnect a bot

Open the Slack integration to view connected bots, their bound Agents, Slack team details, and connection status.

Select Disconnect to remove the bot binding from Sharkly. The Agent will stop receiving messages through that bot. Disconnecting does not turn past Slack messages into Tasks and does not delete Slack conversation history.

If the Slack app must also be removed from Slack, do that through Slack's app administration controls.

#Permissions and security

• Organization Owners and Admins connect or disconnect the shared Slack workspace and change its Linkbacks or Unfurls settings. Organization members can read the connection status.
• Organization members can create and manage Agent bot bindings for Personal Agents they own and Space-shared Agents they are allowed to use. Organization Owners and Admins can manage all Agent bot bindings in the Organization.
• The App Configuration Refresh Token is exchanged during setup and is not used as the installed bot token.
• The generated client secret, signing secret, and OAuth bot token are encrypted at rest.
• OAuth state links the authorization callback to the pending bot installation.
• Slack Events API callbacks are verified with the stored signing secret. Requests with a missing or invalid signature are rejected.
• Incoming event bodies are size-limited, and bot-authored or non-plain message events are ignored.
• The app requests scopes for mentions, direct messages, channel and private-channel thread history, sending messages, opening direct messages, and Assistant status updates.

Use a Slack administrator account with appropriate installation rights. Review the generated app's scopes before authorization and remove unused bot bindings promptly.

#Troubleshooting

#No Agent is available

Create an Agent, or disconnect the existing Slack bot from the Agent you want to use. An Agent already bound to Slack is not selectable.

#The refresh token is rejected

Generate a new App Configuration Token in Slack and copy its Refresh Token. Make sure the complete token is pasted without extra spaces and that the Slack account can create apps.

#The authorization window does not complete

Allow pop-up windows and finish the Slack OAuth prompt in the window opened by Create & Install. The bot remains in Installing until the OAuth callback stores the installed bot token.

#A channel message gets no reply

Confirm the bot is still connected, then check whether that channel uses mention, emoji reaction, or any-message. By default, start by mentioning the bot. After the bot has replied, continue inside that same thread. If the bot should respond without a mention, confirm that Any channel message is enabled for the channel and that its thread option matches where the message was posted. If it should respond to a reaction, confirm the emoji trigger is on and that the reaction matches the configured emoji.

#The bot does not reply to a direct message

Confirm that the bot status is Connected and that the Slack app's Messages tab is enabled. If the app was changed in Slack after creation, restore the required event subscriptions and bot scopes or reconnect the bot.