Connect an Agent to Slack

Each Agent connects to Slack through its own Slack app, so its name and avatar identify it in conversations. Once connected, people mention the app to start work, follow progress in the thread and answer the Agent’s questions there. For how Slack conversations map to Sessions, see Slack.

Before you begin

  • The Agent is deployed to the Environment you want to connect. See Deploy.
  • You have agent_connections.read and agent_connections.configure on this Agent. Connecting an Agent is done in the Console; there is no CLI command or /v1 API for it.
  • The deployment operator has enabled Slack. The Console shows the delivery mode selected for the deployment: HTTP callbacks or Socket Mode. HTTP needs a public HTTPS callback origin. Socket Mode needs outbound HTTPS and WebSocket access to Slack, and can use a private Console origin. Your browser must reach both Slack and the Console for installation and identity linking; join your company network first when the origin is private.
  • You can create apps in the Slack workspace.

Create the Agent’s Slack app

  1. In the Console, select the Environment, open Agents, choose the Agent, and open its Slack tab. The tab walks you through the setup in three numbered steps.
  2. Choose Connect Slack. Each Agent has one Slack connection per Environment.
  3. Choose Create app in Slack. Slack opens with an app manifest already filled in: the app name, bot user, the scopes Helmr needs, and the delivery settings for this connection. The manifest is also shown in the Console if you prefer to paste it.
  4. Create the app. The credential form is shown with the manifest. From the app’s Basic Information page in Slack, copy the Client ID, Client Secret. For HTTP callbacks, also copy the Signing Secret. For Socket Mode, generate an App-Level Token with connections:write in that same app’s Basic Information page.
  5. In the Console, enter the three values and choose Save app credentials. For HTTP callbacks, retry event URL verification in Slack if it previously failed.
  6. Choose Install app in Slack and approve the installation.

Slack may show a token-rotation setup notice while creating the app. Keep token rotation enabled; Helmr refreshes expiring installation tokens. The app is configured to appear online in Slack. This indicator is not a server-health check.

The Slack tab shows the app and workspace once it is authorized. Socket Mode also shows the event connection separately. An authorized app can have a reconnecting or unavailable event connection. If it asks for action, verify that the app-level token belongs to this app and has connections:write, or ask the deployment operator to check network access. Secrets are never returned by the Console/API. From the same tab you can update the app credentials, reauthorize the app, or disconnect it. Before installation, Discard setup releases the Agent’s connection without deleting the app in Slack.

Use it in a channel

Invite the app to each channel where you want to use it, then mention it with a request:

/invite @reviewer
@reviewer Review issue 42

The mention starts a Session. The Agent’s progress, questions and response appear in the thread. To send more input, reply in the thread and mention the app again; messages that do not mention the app are treated as discussion and ignored.

Use direct messages

Open the app’s Messages tab and send a request without a mention. Each new message outside a thread starts a new Session. Reply in that message’s thread to continue; mentions are not needed in DM replies either. Replies to a closed Session, an account-linking hint or a thread without an accepted Session do not start new work. Send a new message outside the thread instead. An unbound reply may wait up to one hour for its root to be accepted before a hint is sent.

DM records are shared under Helmr’s existing Environment permissions. Authorized members can inspect the Session’s input and output in Console even though the Slack conversation is one-to-one. The app’s description and Messages tab guidance also explain this visibility. Group DMs and shared conversations are not supported.

For an existing app, open Update app manifest in the Console’s Slack tab. Copy the current manifest into that same app’s App Manifest settings in Slack and save it. Then choose Reauthorize in Slack for the same workspace to grant the DM permissions. Updating Helmr alone does not update the Slack app. Existing channel conversations remain available before reauthorization. As with any reauthorization, previously unsent output is not backfilled; finish active conversations before updating the authorization.

Work requested in Slack runs as the Helmr user who asked. Each person links their Slack account once per workspace:

  • From Slack: the first time they request work or answer a question, the app sends them a link that asks them to sign in to Helmr and confirm both accounts. Their first action is not applied; they repeat it after linking. In a DM, send a new message outside the linking hint’s thread.
  • From the Console: open Account settings from the profile menu; Profile lists linked identities under Your Slack identity. Choose a workspace and Verify Slack identity.

Linking uses the person’s existing Helmr permissions. Unlinking stops future requests and answers from that Slack account; work already accepted continues.

Route a Session started elsewhere to a channel

A Session started from the CLI, the SDK or a schedule can post into a Slack channel of the connected workspace. Pass the channel’s ID (for example C0123456789, shown in Slack’s channel details), not its name. The Agent’s app must be able to access the channel.

helmr session create reviewer --project demo --env staging \
  --slack-channel C0123456789 --text "Review issue 42"
await client.sessions.create({ agent: "reviewer", input: [{ type: "text", text: "Review issue 42" }],
  slack: { channelId: "C0123456789" }, })

For scheduled work, set slack: { channelId } on the cron trigger; see Triggers. The start fails if the Agent has no connected Slack app or cannot access the channel.

Repair or disconnect

If Slack authorization is lost, the connection asks for repair. Choose Reauthorize in Slack for the same app and workspace; output that could not be posted in the meantime is not posted afterward. To change the app’s credentials, use Update app credentials.

Disconnect Slack stops Slack input, answers and output in existing threads. Sessions continue and remain available through the CLI and API. Reconnecting creates a new connection: earlier threads stay disconnected, and triggers that post to Slack take effect again only after a Deployment is promoted. Disconnecting does not delete the app in Slack.

Deployment settings

The operator sets APP_ORIGIN, SLACK_TRANSPORT=disabled|http|socket and, when needed, OUTBOUND_PROXY_URL. These are deployment configuration, not organization settings. Organization owners/admins manage only their Agent’s dedicated Slack app and its credentials. HTTP delivery registers /integrations/slack/apps/{registrationID}/events and /interactions; Socket and disabled deployments do not mount those receivers. Both enabled modes use browser callbacks at /auth/slack/callback and /api/slack/user-links/callback.

Changing the deployment transport does not convert existing registrations. Disconnect and set up the connection under the new mode. There is no automatic fallback between transports. Socket Mode apps cannot be distributed through the Slack Marketplace; this workflow uses dedicated workspace apps.