Attachments and file context

Chat can upload a managed copy with one message, keep a live reference to an item in the SoAI workspace, or index a collection as Knowledge for retrieval across later prompts. One message can use several of these methods together.

Attachment controls are conditional. On a fresh installation, Chat enters the sidebar after the catalog has a selectable conversation model. Appearance settings control the Upload and Scan entry points. Model capabilities control the form of content sent to the provider. See Chat for the first-run model requirement and the wider Chat control visibility table.

Your account needs Files reading (FILE_EXPLORER_READ) for Workspace and SoAI link operations. Knowledge needs RAG access (RAG_USE), and Load from Workspace needs both. Global Search needs Internal search access (SEARCH_READ). Its Files results also need Files reading (FILE_EXPLORER_READ) and show only items in your account's workspace. The default policy grants all three actions to Administrator and Standard user accounts. An Administrator with ACL administration (ACL_ADMIN) selects the Settings button at the right of the header, chooses Settings, then opens ACL to change them.

Choose how to add the source

Direct uploads, scans, and sketches belong to one message and remain visible in its conversation history. Workspace file and folder references and SoAI links point to stored workspace items; Workspace can also link completed Knowledge from another conversation. Only Knowledge creates a searchable conversation collection.

Receive files from a messaging app

Discord, Telegram, and WhatsApp users can send supported files to a messaging account. The server downloads each file, applies the same size limit and processing used for a direct Chat upload, and attaches the result to the matching conversation. The selected model receives the processed attachment with the message text or caption. See Connect messaging apps to SoAI and the provider-specific guides for the file types each app supports.

Open the attachment picker

1. Open an existing conversation or start a new one.
2. Select Add attachments beside the composer.
3. Choose Upload, Scan, Workspace, SoAI link, or Knowledge.
4. Add the sources, close the picker, and review the attachment cards above the composer.
5. Wait for direct files and any draft Knowledge attachments to finish processing, then send the message.

If Add attachments is not visible, open Chat configuration, choose Appearance, expand Input actions, and enable Upload file. The Upload tab follows that setting. The Scan tab follows the Camera input action. Workspace, SoAI link, and Knowledge remain enabled whenever the picker is open. A valid SoAI link can also be pasted into the main composer.

Open sketch is a separate composer action. Enable Sketch under Chat configuration > Appearance > Input actions, draw in the sketch pad, then select Attach. SoAI uploads the drawing through the same direct-file path as Upload; review its card before sending. Closing a sketch with unsaved strokes asks whether to discard them.

Controls that appear only when they apply

Upload files and folders from your device

In Add attachments > Upload, select Upload file to choose one or more files. Select Upload folder to choose a folder, or drop files and folders onto the Upload pane. You can also drag them over an open Chat conversation; when the conversation can accept the drop, SoAI opens the Upload tab for you.

A folder upload expands the folder into separate message attachments, and you can remove any item you do not want before sending. A workspace folder stays a live folder reference, while a Knowledge folder becomes part of an indexed collection.

The picker accepts a broad range of file types instead of enforcing a short MIME list. Each file needs a usable name, at least one byte of content, and a size within the installation's upload limit. A recognized image MIME type or image header enables the visual-image path. Other files, including image-looking files that fail that check, go through document parsing. If no parser extracts useful content, the card can finish as Reference only. The selected model still needs the right capabilities to use the result.

Drag and drop works in a conversation that can accept attachments. Conversation selection and blocking dialogs suspend it. To add a local clipboard file or image, use Upload or Scan; composer paste is reserved for text and SoAI links.

Attach a Workspace file already stored in SoAI

1. Open Add attachments > Workspace.
2. If needed, select Change folder and choose the Files folder used by this conversation.
3. Enter a name in Search SoAI files.
4. Select a result. Use Preview to inspect it, or Attach to add it to the draft.
5. Repeat the search and selection when you want to add more results.

Workspace search uses the conversation's effective workspace and requires Files reading (FILE_EXPLORER_READ). It can also show completed, reusable Knowledge sources. A file or folder result becomes a live reference, not another upload. A Knowledge result instead links its completed items into the current conversation.

Start from Global Search or Files

Global Search can find files and documents anywhere you can access in your workspace. Enter at least two characters in the header search and select a file result. The result opens in Files; a folder result opens its location there.

1. In the file preview, select Attach. For a folder or several Files items, select them in Files and select Attach or Attach (count).
2. SoAI copies one or more SoAI links to the browser clipboard. You choose the target conversation afterward.
3. Open the target conversation and paste the links directly into the main composer, or open Add attachments > SoAI link and paste them there.
4. SoAI resolves each valid link and adds an attachment card. Review the cards before sending.

This flow works for files, documents, images, audio, video, and folders that your account can read in the workspace. The preview's Attach action copies a reference and needs browser clipboard support. Use Add attachments > Workspace when the item is inside the conversation's current workspace. For an item elsewhere, use Change folder to select the workspace that contains it.

Paste SoAI links directly into the composer

The normal message field recognizes one or more SoAI links among your text. It resolves the tokens, removes their encoded form from the message, and adds the corresponding attachment cards. The dedicated SoAI link tab does the same job when you want a separate field for several copied links.

SoAI links are specific to SoAI workspace items. A normal web URL or local operating-system path is not a SoAI link and will not become an attachment through this field.

How SoAI protects linked workspace content

The server resolves each link inside the conversation's effective workspace and under the current user's Files permissions. Arbitrary host paths are outside this route. It records the workspace identity and a fingerprint of the target, then verifies both for every request. A changed, moved, missing, retyped, or inaccessible item produces a changed or unavailable notice. The old card never authorizes different content (even if a replacement uses the same path).

A linked file can be exposed to the model through enabled file-reading tools when the selected model supports tool calling. Otherwise it attempts to parse and place its content inline. A linked folder can be navigated through enabled file tools; without those tools, the server supplies a bounded folder listing instead. See File and shell tools for the model-facing workspace tools.

Mix several sources in one message

Ordinary uploads, folder-upload files, camera captures, Workspace references, pasted SoAI links, and Knowledge can all coexist in one draft. You can use different methods again later in the conversation. When Knowledge attachments are still pending, running, or cancelling, wait for them to reach a terminal state before submitting the message.

Six attachment cards fit in the inline composer or message strip. The overflow control opens Message attachments for the rest, with search and filters for Attachments, Knowledge, and SoAI links. Six is a display limit, not a file-count limit.

More attachments do not create more model context. Long extracted text shares a bounded context budget, so adding several large documents can reduce how much text SoAI includes from each one. Ask focused questions, attach only the relevant files, or use Knowledge when the collection is too large for direct inline reading.

What reaches the selected model

The provider receives a prepared projection of each attachment. SoAI chooses it from the source type, parser result, selected model capabilities, available tools, and configured limits.

Images and camera scans

Common image formats can be attached through Upload, Workspace, a SoAI link, Scan, or Sketch. A vision-capable model receives normalized visual input within the configured pixel and encoded-size limits. OCR text can accompany the image. If visual preparation fails and OCR succeeded, SoAI can still use the extracted text.

Scan captures a browser camera frame as a JPEG. Switch camera requests the other facing mode on devices that offer one. Select Capture, use Retake if needed, then select Use photo. A vision-capable selected model receives prepared visual input. Other cases use the document and OCR path. Camera support and permission come from the browser and operating system.

Video and audio

Video parsing has two separate outputs. SoAI attempts to transcribe the audio track and read visible text from sampled frames. For a vision-capable model, request projection can also include timestamped still frames. The request has one frame allowance for all distinct videos. SoAI starts with the newest videos, assigns one frame to each selected video, then distributes the remaining allowance among them.

Parsing and model input have separate bounds. By default, the parser samples at one frame per second for OCR, up to 360 frames and 250,000 characters of visible text. The later model request can carry no more than 12 sampled visual frames across all videos. With more than 12 distinct videos, only the newest 12 receive a visual frame; the others carry an omission notice. Transcript or OCR text can cover more of a video than the visual frames sent to the model.

Audio parsing reads basic media metadata and attempts speech transcription. Transcription requires an installed local speech-to-text plugin backend and model; see Set up speech-to-text. A file can finish with a degraded result even though the upload itself succeeded. A missing speech setup is recorded as Speech not transcribed. Set up a model, then re-ingest the retained source or add the file again to obtain a transcript. For agent-controlled inspection after a chat has started, see Media reading tools.

Documents and other formats

SoAI has parsers for these practical groups:

• plain text, Markdown, source code, logs, and configuration files;
• CSV, JSON, XML, HTML, and Jupyter notebooks;
• PDF, Word, Excel, PowerPoint, and OpenDocument files;
• EPUB and other supported ebook formats;
• EML, MSG, MBOX, and supported messaging exports;
• ZIP, TAR, and other archives supported by the installed parser stack;
• common image, audio, and video formats.

Parser availability can depend on installed libraries, and successful extraction does not promise perfect layout, OCR, transcription, spreadsheet formulas, or archive coverage. The Upload picker may accept a format that later becomes reference-only. For parser internals, chunking, OCR, and indexed ingestion, use Knowledge and document collections (RAG) instead of treating direct attachments as RAG.

Processing states and sending

Removing an unsent direct attachment cancels its remaining processing and removes its managed storage when safe. After a message is sent, its cards remain part of the transcript. Available cards can expose preview, open, or download actions according to the source and your access.

When the saved file behind an attachment is missing or no longer matches its record, SoAI does not serve its content. The preview reports that the attachment is unavailable. To use the file again, open Add attachments, choose Upload, select Upload file, and add it to a new message.

An attachment read can be temporarily unavailable because file workers are busy or the read times out. Your message, other usable attachments, and the saved file remain available. Follow Recover file uploads and attachment reads to retry before replacing the attachment.

Current default limits

These values are the shipped defaults. To change one in the SoAI WebUI, an Administrator with Configuration changes (CONFIG_PATCH) selects the Settings button at the right of the header, then Settings and the page-header Advanced toggle. Select the generated configuration tab containing the named setting, edit it, and select the page-header Save control. The Advanced toggle is hidden unless both requirements are met. The WebUI reads the effective direct-upload limit from the server.

Ordinary direct attachments have no separate fixed count. Per-file size, processing resources, request size, model context, provider capability, and administrator settings still bound a practical request.

Use Knowledge for a searchable collection

Use Add attachments > Knowledge for a collection that must remain searchable. This requires RAG access (RAG_USE). Upload files or a folder, or select Load from Workspace. In the Import folder prompt, enter a Files path such as /path/to/folder. SoAI queues a recursive import. The items are searchable only after parsing, chunking, and embedding complete.

Knowledge requires an embedding model. Open Models catalog to download one or follow its External provider setup to connect an OpenAI-compatible embedding provider. Bundled plugins reference describes the local Embedding and External plugin capabilities. The conversation model also needs tool-calling support to search Knowledge while answering. Auto (embedding) selects from embedding models already available in the catalog. Download or connect the model first; Auto neither downloads a model nor changes a chat model's capabilities.

Retrieval also requires Enable RAG under Chat configuration > Knowledge and the required Knowledge tools to be available. When the collection and model are ready, SoAI keeps those tools enabled for the conversation.

Load from Workspace ingests files into the collection. Attaching a Workspace file or folder keeps a live reference instead. Completed reusable Knowledge sources can appear in Workspace search for another conversation owned by the current user, subject to the installation's item limit.

Knowledge controls are also conditional. Reindex appears once the collection has documents and is enabled only when an embedding model is configured. For the full WebUI setup, retrieval settings, parser behavior, and indexing lifecycle, see the Knowledge section in Chat and the technical Knowledge and document collections (RAG) page.

Troubleshooting

Related documentation

• Chat for conversation setup, controls, visibility rules, and Knowledge configuration.
• Connect messaging apps to SoAI for files received through Discord, Telegram, or WhatsApp.
• Models catalog for downloads and model capabilities such as vision, embeddings, and tool calling.
• Bundled plugins reference for local and external inference or embedding providers.
• Knowledge and document collections (RAG) for indexing, chunking, embedding, OCR, and retrieval internals.
• File explorer for workspace access and Files permissions.
• File and shell tools for model-controlled workspace access.
• Media reading tools for agent-controlled image, audio, video, and document inspection.
• Users, roles, and sessions for roles and access permissions.
• Configuration for every server-side attachment limit.