How Slack files reach the agent turn, and how Apus sends text and media back.

Voice input

To speak to Apus in Slack today, send a Slack audio clip to the Apus app. Slackbot's dictation microphone is a separate Slack-owned feature, not an app API.

• Slackbot voice dictation lives inside the user's private Slackbot conversation. Slack turns the recording into a Slackbot prompt but does not emit an audio file, dictation event, prompt, or input-source marker to third-party Slack apps through the Events API. The Apus Slack plugin cannot enable or receive it.
• Slack audio clips are stored Slack files that can be posted in an Apus DM, channel, or thread. Apus downloads an accessible clip with the bot token, normalizes Slack's clip MIME metadata, and sends it through the shared audio transcription pipeline. The recommended app manifest includes the required files:read scope.

Audio clips and Slackbot dictation have different privacy semantics: clips follow Slack file-retention policy and Apus downloads them for transcription, while Slack says dictation audio is not stored.

In a channel with requireMention: true, a captionless audio clip can satisfy the gate by speaking a configured mention pattern (agents.entries.*.groupChat.mentionPatterns, falling back to messages.groupChat.mentionPatterns). Apus authorizes the sender before downloading or transcribing the clip, then admits it only when the transcript matches. A failed or nonmatching speculative transcript is discarded with the downloaded clip; it is not retained in channel history. Native Slack @bot identity cannot be inferred from speech, so configure a spoken-name pattern or include a typed mention. If transcript echoing is enabled, the echo is sent only after admission.

Media, chunking, and delivery

Slack file attachments are downloaded from Slack-hosted private URLs (token-authenticated request flow) and written to the media store when fetch succeeds and size limits permit. File placeholders include the Slack `fileId` so agents can fetch the original file with `download-file`.

Downloads use bounded idle and total timeouts. If Slack file retrieval stalls or fails, Apus keeps processing the message and falls back to the file placeholder.

Runtime inbound size cap defaults to `20MB` unless overridden by `channels.slack.mediaMaxMb`.

- text chunks use `channels.slack.textChunkLimit` (default `8000`, capped at Slack's own message-length limit)
- `channels.slack.streaming.chunkMode="newline"` enables paragraph-first splitting
- file sends use Slack upload APIs and can include thread replies (`thread_ts`)
- long file captions use the first Slack-safe text chunk as the upload comment and send remaining chunks as follow-up messages
- text and context blocks preserve code formatting and literal backslashes across section boundaries
- outbound media cap follows `channels.slack.mediaMaxMb` when configured; otherwise channel sends use MIME-kind defaults from media pipeline

Native Block Kit sections retain all fields even when their combined accessibility text exceeds the preferred text chunk size. Slack's block limits and the 40,000-character message text hard limit still apply.

Preferred explicit targets:

- `user:<id>` for DMs
- `channel:<id>` for channels

Text/block-only Slack DMs can post directly to user IDs; file uploads and threaded sends open the DM via Slack conversation APIs first because those paths require a concrete conversation ID.

Attachment media reference

Slack can attach downloaded media to the agent turn when Slack file downloads succeed and size limits permit. Audio clips can be transcribed, image files can pass through the media-understanding path or directly to a vision-capable reply model, and other files remain available as downloadable file context.

Downloading an attachment by file ID

The message tool's download-file action requires a Slack fileId from a message or file placeholder. It uses the current Slack channel unless you provide an explicit channelId. An explicit threadId additionally requires the file to be shared in that thread; an ambient conversation thread does not narrow a channel-only download.

Apus checks the channel's existing access policy and fresh files.info share evidence before downloading. It repeats the file-share check if Slack refreshes an expired download URL. Verified official npm and ClawHub installations use the same provider checks as the bundled Slack plugin.

An allowed download returns the existing local media artifact. Images also return image content within the configured image dimension limit. The configured read credentials, Slack/GovSlack host restrictions, HTTPS and redirect checks, and channels.slack.mediaMaxMb size cap continue to apply. For agent downloads, a canceled or revoked read cannot return an accepted artifact; cleanup removes its own newly created file while preserving preexisting or replaced files.

Supported media types

Inbound pipeline

When a Slack message with file attachments arrives:

1. Apus downloads the file from Slack's private URL using the bot token.
2. The file is written to the media store on success.
3. Downloaded media paths and content types are added to the inbound context.
4. Audio clips are routed to the shared transcription pipeline; image-capable model/tool paths can use image attachments from the same context.
5. Other files remain available as file metadata or media references for tools that can handle them.

Thread-root attachment inheritance

When a message arrives in a thread (has a thread_ts parent):

• If the reply itself has no direct media and the included root message has files, Slack can hydrate the root files as thread-starter context.
• Root files are hydrated only while seeding a new or reset thread session. Later text-only replies reuse the existing session context and do not reattach root files as fresh media.
• Direct reply attachments take precedence over root-message attachments.
• A root message that has only files and no text is represented with an attachment placeholder so the fallback can still include its files.

Multi-attachment handling

When a single Slack message contains multiple file attachments:

• Each attachment is processed independently through the media pipeline.
• Downloaded media references are aggregated into the message context.
• Processing order follows Slack's file order in the event payload.
• A failure in one attachment's download does not block others.
• Failed or blocked files remain in the agent context with a bounded reason, and each failed file produces one warning after any URL refresh retry.
• Files beyond the eight-file limit are not downloaded. Their references carry an omitted: 8-file limit reason. Long unavailable-file lists are visibly truncated, while the notice retains the total unavailable attachment count.

Size, download, and model limits

• Size cap: Default 20 MB per file. Configurable via channels.slack.mediaMaxMb.
• Audio transcription cap: the selected audio-capable tools.media.models[] entry's maxBytes also applies when the downloaded file is sent to a transcription provider or CLI.
• Download failures: Files that Slack cannot serve, expired URLs, inaccessible files, oversize files, and Slack auth/login HTML responses are skipped instead of being reported as unsupported formats.
• Vision model: Image analysis uses the active reply model when it supports vision, or the image model configured at agents.defaults.imageModel.

Known limits

Related documentation

• Media understanding pipeline
• Audio and voice notes
• PDF tool