1. integration
Sharkly docs
  • Welcome to Sharkly
  • Quickstart
  • agent-and-computer
    • Agents
    • Chat with an Agent
    • Agent task execution
    • Comments and replies
    • Inbox
    • Repositories
    • Skills
    • Crews
    • Computers
  • task
    • Task types
    • Task statuses
    • Task relations
    • Task labels
    • Task subscriptions
  • integration
    • Jira integration
    • Slack integration
  • space
    • Spaces
    • People
    • Tasks
    • Projects
    • Automations
    • Views
    • Sprints
  • cli
    • Sharkly CLI
    • Personal access tokens
  1. integration

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.
Disconnecting the Slack workspace stops Task creation, linkbacks, and link previews from that Slack workspace. It does not delete existing Sharkly Tasks or Slack messages.

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 Add Bot.
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#

A bot can also be configured with an Any message trigger for selected channels. When enabled, ordinary messages in those channels can start the Agent without a mention. An additional thread option controls whether messages in channel threads can also trigger it.
Use this setting 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 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#

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 the Any message trigger is enabled for the channel and that its thread option matches where the message was posted.

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.
Modified at 2026-08-04 04:02:55
Previous
Jira integration
Next
Spaces
Built with