Slack
Install nima in Slack: scopes, which messages become signals, per-channel settings, emoji, clarifying questions, ship notices and disconnecting.
Connecting Slack makes your team's channels a signal source and gives your team a bot to talk to. Messages in channels nima has joined, and direct messages to it, arrive as evidence tied to the Slack thread they came from. People in your workspace can also mention or message nima to ask questions. That side is covered in Slack assistant.
On for every workspace. An owner or admin installs it; the Slack routes are declared under the slack_ingestion plan feature.
Install nima in Slack
An owner or admin of the nima workspace installs the Slack app from Integrations in the admin panel. Members without the integrations permission cannot start the install.
- Sign in to nima as an owner or admin and open Integrations.
- On the Slack tile, press + (Connect Slack), choose your Slack workspace and allow the install. Slack may require a Slack admin to approve the app.
- Invite
@nimato each channel you want it to read:/invite @nima.
Things to know:
- One Slack workspace per nima workspace. Connecting again replaces the existing installation, its token and its bot user.
- People are linked by email. At install nima matches every Slack account to a nima account by the email on the Slack profile. New Slack members are matched when they join, and an unlinked person who mentions nima or runs an admin command is matched on the spot. The nima account must be a live member of this workspace.
- Joining a channel creates its settings. When the bot joins a channel, nima creates that channel's settings with the type
CUSTOMER_FEEDBACK, clarifying questions off and the channel active. If the bot rejoins a channel that was inactive, nima reactivates it. - The result shows in the admin panel. After the redirect, Integrations shows Slack as connected. If the install fails, the page shows an error message instead.
Slack scopes
nima requests 27 bot scopes when you install. Fourteen are used; thirteen (bookmarks, canvases, pins, channel management, app_mentions:read, chat:write.customize, files:write and users.profile:read) are requested but no code path uses them today. Mentions of nima arrive as ordinary message events and are read with the history scopes.
| Scope | Used | What nima does with it |
|---|---|---|
channels:history, groups:history, im:history | Yes | Read messages, including mentions of nima, in channels nima is in and in DMs to it |
channels:read, groups:read | Yes | List channels and read names and member counts for the channel picker |
chat:write | Yes | Reply in threads, post notices, send DMs |
im:write | Yes | Send DMs for reminders, approval cards and questions |
reactions:read, reactions:write | Yes | Add and clear nima's own emoji; read the bell reactions |
files:read | Yes | Read images, video, PDFs and other files attached to a message |
users:read, users:read.email | Yes | Link Slack accounts to nima accounts, read display names and time zones |
assistant:write | Yes | Show the "thinking" status while nima prepares an answer |
commands | Yes | The /nima slash command for owners and admins |
bookmarks:read, bookmarks:write | No | Requested, unused |
canvases:read, canvases:write | No | Requested, unused |
pins:read, pins:write | No | Requested, unused |
channels:manage, channels:write.invites, channels:write.topic | No | Requested, unused |
files:write | No | Requested, unused |
chat:write.customize | No | Requested, unused |
users.profile:read | No | Requested, unused |
app_mentions:read | No | Requested, unused; mentions arrive as ordinary message events |
nima stores the bot token encrypted.
Which Slack messages become signals
nima turns every message in any channel the bot is in, and every DM to the bot, into a signal. It does this whether or not the message mentions nima, and whether or not the channel is marked paused. Bot messages and nima's own messages are ignored. So are messages nima handles as commands: agent ... and admin commands (github-writer, mcp-key, confirm) addressed to nima, a stop DM when watches are on, and answers to a question nima relayed in a DM.
- Each top-level message becomes a new signal, with the channel name and who posted it. nima then classifies it. A message that extraction judges to be noise is dismissed, except that messages about pricing, compliance or contract terms are always kept.
- Thread replies attach to the signal for that thread and extraction runs again. A reply to a thread that has no signal yet starts a new one.
- Edits do not re-extract. When a message is edited, nima updates the stored text only; the signal keeps what extraction already read.
- Deletes dismiss a sole source. When a message is deleted, nima deletes its stored copy and dismisses a signal whose only source was that message.
- There is no backfill. nima reads only what is posted after the bot joins a channel. Older history stays in Slack.
- There is no keyword or author filter. To stop nima reading a channel, remove the bot from it.
A channel's per-channel settings do not gate reading. Pausing a channel does not stop signals, and silent mode stops what nima says, not what it reads. See Per-channel Slack settings.
Every Slack signal links back to its thread, and get_signal_source re-reads the thread live from Slack when it is called. See MCP tools for the pipeline.
Slack attachments in ingested messages
nima reads attachments on ingested messages, with rough edges. Signals built from messages handle files as follows.
| Attachment | What nima does |
|---|---|
| Images | Described by a vision model and added to the signal's text |
| Video files | Reduced to at most 5 key frames; the audio track is not analysed |
| Audio files | Not supported; skipped |
| Loom and YouTube links | Recorded as a line with the URL; the video is not watched |
| PDFs | Decoded crudely as text; scanned or compressed PDFs yield little |
| Plain text, CSV, HTML, Markdown, JSON, XML | Read as text |
Size limits are 10 MB per file and 30 MB per message. When someone mentions or DMs nima directly, the assistant handles attachments differently, including audio, video and PDFs. That is described in Slack assistant.
Emoji nima adds in Slack
nima reacts on the source message to show where a signal stands.
- 👀 (
eyes) when nima creates a signal from the message. - 🐛 (
bug) for a bug, ✨ (sparkles) for a feature request, ⚠️ (warning) for spec drift. The classification emoji replaces 👀. If the classification changes, nima swaps the emoji. - No emoji for customer feedback, performance, documentation or question classifications: nima only clears 👀.
- Cleared when a signal ends without action, such as noise, a failed extraction or a dismissal. Removal always happens, even in a silent channel.
If an answer from nima's assistant is still being written for a message, 👀 stays up until the answer lands. A channel with acknowledgments off, or a silent channel, gets no 👀 and no classification emoji.
Reactions from your team are mostly ignored. The exception is the bell: with watches turned on for the workspace, 🔔 on a message nima filed as a signal starts a watch and 🔕 pauses it. See Watches and reminders.
Clarifying questions in Slack threads
nima can ask a question in the thread when a report is too thin to act on. Two independent mechanisms exist, so one thread can see more than one question in total.
- Signal extraction asks at most one question per signal, only for an actionable signal, and only when the channel's clarifying questions are not switched off. It addresses the poster. Their reply re-runs extraction.
- Pre-signal analysis applies only to active channels with settings. nima waits 60 seconds after the last message in a thread, assembles the thread, classifies its intent (bug report, feature request, question, feedback or urgent incident) and groups it with similar threads. It asks at most one question per thread. If the thread contains video and clarifying questions are on, nima first posts a note that it is extracting up to 5 key frames per video. Read these analyses with
GET /v1/slack/monitoring/insights; they do not create signals or beacons by themselves.
Clarifying questions are off by default in a channel created when the bot joins (while the channel is active), and on by default for a channel you create as BUGS. Turn them on or off per channel with clarificationEnabled.
Per-channel Slack settings
Each channel nima has joined has a settings row. The admin panel exposes one control, on or off; the other settings are reachable only through the API with a signed-in owner or admin session.
| Setting | Default | What it does |
|---|---|---|
isActive | true | The admin panel's on/off toggle, labeled Paused when off. Pausing does not stop signals. While a channel is paused, nima ignores its other settings and uses the defaults for a channel with no settings: it is not silent, it adds emoji, extraction may ask clarifying questions, pre-signal analysis stops, and 🔔 is refused. |
silent | false | nima says nothing in the channel: no answers, acknowledgments, thinking status, clarifying questions, ship notices, VM task replies or outbound posts, and no 👀 or classification emoji. It still reads and files signals, and it still removes its own emoji. |
acknowledgmentsEnabled | true | Whether nima adds 👀 and the classification emoji. silent overrides it. |
clarificationEnabled | true for BUGS channels, else false | Whether nima asks clarifying questions. silent overrides it. |
autoSkipEnabled (maxClarificationQuestions is stored but ignored: nima asks at most one question per signal and one per thread) | false | Noise dismissals in this channel get the reason auto_skip, which hides those signals from every signal list and count, including dismissed ones. Pricing, compliance and contract topics are never auto-dismissed. |
The settings routes live under /v1/slack/monitoring, take a first-party session, and require the owner or admin role. They are not reachable with API keys or OAuth tokens.
| Route | What it does |
|---|---|
GET /v1/slack/monitoring/channels | List channel settings, up to 100 |
GET /v1/slack/monitoring/channels/picker | List every channel nima can see with whether it is monitored and whether the bot is a member |
POST /v1/slack/monitoring/channels | Create settings for a channel by slackChannelId and channelType |
PATCH /v1/slack/monitoring/channels/:id | Change channelType, sourceType, clarificationEnabled, maxClarificationQuestions, isActive, silent, acknowledgmentsEnabled or autoSkipEnabled (maxClarificationQuestions is stored but ignored: nima asks at most one question per signal and one per thread) |
DELETE /v1/slack/monitoring/channels/:id | Delete the settings row |
DMs to nima, and channels whose settings row was deleted, use the same defaults as a paused channel.
A change applies from the next message: saving a setting clears nima's cached copy. A thread already waiting on pre-signal analysis (up to 60 seconds) keeps the clarification setting it had when its last message arrived.
Ship notices in Slack threads
When a spec ships, nima replies in each Slack thread whose signals fed that spec. The text is Shipped: <spec title> — <PR url>, and it links the pull request, not the spec. nima sends one reply per thread, up to 20 threads per spec. A failed post, such as one in an archived channel, does not stop the others. Nothing is sent in a silent channel or when no Slack installation exists. See From spec to shipped.
Slack Connect channels
nima treats channels shared with another organization as riskier. Signals from a Slack Connect channel are still ingested. But 🔔 on a message in a shared channel is refused, and an outbound channel post that uses the ship-announcement template is not sent to a channel that is shared, or may be shared, with another organization. The automatic ship notice in the originating thread is still posted there. nima answers only people whose Slack profile email matches a live member of this nima workspace. A Slack Connect user or guest from another company usually has no such account. When they mention nima they get a short reply saying nima only answers workspace members, and nima ignores their follow-ups in the thread.
Disconnect Slack
There are three ways to disconnect Slack. An owner or admin can press Disconnect on the Slack tile in Integrations, call POST /v1/slack/app/uninstall with an owner or admin session, or uninstall the nima app from the Slack workspace in Slack's app settings. When the app is uninstalled from Slack's side (Slack sends app_uninstalled or tokens_revoked), nima stops reading and soft-deletes the installation and its user mappings. The Slack tile in Integrations keeps showing Slack as connected until an owner or admin presses Disconnect or reconnects. Disconnecting from nima does not remove the app from Slack. To remove the bot from Slack as well, uninstall it there. The tile's On/Paused switch does not stop Slack ingestion.
Disconnecting from nima soft-deletes the installation and its user mappings and removes the integration record. Reinstalling restores the installation and its mappings, and nima re-matches members by email. Disconnecting deletes no signals; what nima already collected stays, with its links. Removing @nima from a single channel stops nima reading that channel only.