Skip to content

Slack#

Lens Prism can run in Slack — responding to direct messages and channel mentions, holding threaded conversations, and waking on activity in designated channels. Slack runs over Socket Mode, so no public webhook or inbound URL is needed. Slack is optional; the runtime starts without it.

Set up the Slack app#

You provide the agent with credentials for a Slack app you create:

Variable Value
SLACK_BOT_TOKEN The bot token (xoxb-…). Validated via auth.test on boot.
SLACK_APP_TOKEN An app-level token (xapp-…) with the connections:write scope, required for Socket Mode.
SLACK_EXPECTED_APP_ID Optional. If set, the bot token's app ID must match — a safety check that you wired up the right app.

To set up the app:

  1. Create a Slack app and enable Socket Mode.

  2. Grant the bot the scopes it needs — posting and reading messages, handling DMs and mentions, uploading and reading files, reading user and channel info, and adding reactions. A working set:

    app_mentions:read   chat:write        im:history        im:read
channels:history    groups:history    files:read        files:write
users:read          reactions:write   conversations.connections:write

  3. Subscribe to the bot events the agent handles: message.im, message.channels (and message.groups for private channels), app_mention, member_joined_channel, and member_left_channel.

  4. Install the app to your workspace and copy the bot and app tokens into the runtime's environment — the .env file for a native install, -e flags for Docker. See Configuration.

Note

Exact scope requirements can shift with Slack's API; the list above reflects the events and API calls the agent makes. Grant a scope when Slack tells you a call was denied for lack of it.

Before the agent will talk to you, it needs to know who you are. Linking is started from the web UI Channels page, which issues a short-lived six-character code. Personal Mode and Team Mode are mutually exclusive — unlink all channels before switching to a DM link, and vice versa.

Personal Mode#

To DM the agent:

  1. In the web UI, open Channels and click Link Account under Personal Mode. You get a six-character code (for example A1B2C3), valid for about 15 minutes.
  2. Open a DM with the agent in Slack and send it the code. Slack formatting is tolerated — *A1B2C3* works too.
  3. The agent confirms the link. From then on you can chat with it in that DM.

If an unrecognized person DMs the agent, it replies with a short prompt explaining how to link, rather than answering.

Team Mode#

To link a channel:

  1. In the web UI Channels page, click Add channel to generate a channel link code.
  2. Invite the agent to the Slack channel.
  3. Post the code in the channel. The agent confirms it's now connected.

You can link multiple channels — click Add channel again for each one; linked channels appear in a table, each with an Unlink action. A channel can only be linked to one agent.

When several channels are linked, one is the main channel (marked ★ in the table; the first channel you link becomes main by default). Heartbeat alerts post to the main channel only — never fanned out to every linked channel. Use Set main in the table to move it. Scheduled tasks post to the channel they were created in; if that channel can't be resolved the run is logged as undeliverable rather than rerouted. Replies to your own messages always go back to the channel you wrote in.

How the agent behaves in Slack#

  • DMs. It treats your DM as a conversation thread and replies to everything you send. Your DM history stays in Slack, kept separate from the web chat. You can also reply in a thread on one of the agent's DM messages; the agent keeps that thread's context and replies inside the same thread.
  • Channels. It responds when @mentioned and when you reply within a thread it's already part of. Other channel messages are observed for context but not answered. When a thread it participated in gets a new message, a quick classifier decides whether to reply, react with an emoji, or stay quiet. The agent knows which channel it's replying in, so it can behave differently across linked channels.
  • Threads. Each Slack thread maps to a Prism conversation thread; the agent can read the thread's history, including messages from before it joined.
  • Messages sent mid-reply. Long tasks post progress as they go, and you can post while one is running. A message that lands mid-task is handed to the work in flight: the agent picks it up at its next step and adjusts. Whatever arrives too late for that turn is answered together in one follow-up.
  • Files. You can share files with the agent, and it can share files back. If a file can't be read, the agent tells you why.
  • Feedback. Final messages carry thumbs-up and thumbs-down buttons; tapping one records feedback.

Autonomous messages — heartbeat alerts and scheduled task results — arrive as channel posts. In Team Mode, heartbeat alerts go to the main channel and scheduled tasks go to the channel they were created in; in Personal Mode they arrive in your DM.

Slack-triggered heartbeats#

You can designate a Slack channel as a heartbeat trigger from the web UI Channels page. When a message lands in that channel, it wakes the agent's heartbeat with those messages as context, letting the agent react to real-time channel activity between its scheduled runs. A per-channel throttle caps how often this can fire, and pending messages are queued and drained so none are lost even if several arrive while the agent is busy. See Slack-triggered heartbeats.