> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elitea.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Working with Chat Attachments

Attach files and images directly to chat conversations for AI-powered analysis. This feature enables multimodal interactions where AI can process visual content, documents, and data files alongside text-based queries.

Every file you attach is automatically uploaded to the default `attachments` bucket — no manual Artifact Toolkit configuration is required. Files are accessible from the **Artifacts** section.

* **Images** are sent directly to the LLM for real-time vision analysis.
* **Non-image files** (documents, code, data) are indexed into a vector database and retrieved via semantic search.

## How Attachments Work

The attachment functionality is integrated with the **Artifact Toolkit**.

* **Storage:** Every file you attach is automatically uploaded and stored in an Artifact bucket. The backend always uses the default `attachments` bucket — no manual Artifact Toolkit configuration is required.
* **Access:** This allows the AI agent to access the file for analysis and also provides a centralized location for you to manage these files via the **Artifacts** section of the platform.
* **Retention:** Files are subject to the retention policy of the bucket they are stored in. By default, new buckets have a retention period of 30 days, after which files are automatically deleted. Retention period can be changed manually.

For detailed information about bucket management and retention policies, see the [Artifacts Documentation](https://docs.elitea.ai/menus/artifacts.md).

### Supported File Types

**Image Formats**

Raster images are sent directly to the LLM for visual analysis. Supported formats include:

| Extension | Notes |
| - | - |
| `.jpg` / `.jpeg` | Standard compressed image format |
| `.png` | Lossless compression with transparency |
| `.gif` | First frame only for animated GIFs |
| `.bmp` | Uncompressed raster format |
| `.webp` | Modern compressed format |
| `.tiff` / `.tif` | High-quality raster format |
| `.ico` | Windows icon format |
| `.apng` | Animated PNG format |
| `.avif` | Next-gen compressed format |
| `.svg` | Processed as a document (see note below) |

> [!NOTE]
>
> Raster images are sent directly to the LLM's vision capabilities for analysis. Animated GIFs are processed using only the first frame.
>
> **SVG files** are processed as documents, not as images — they are indexed and retrieved via the document pipeline rather than sent inline to the LLM's vision input. SVG files are also exempt from the per-image 5 MB size limit and do not count toward the image attachment count.

**Documents & Data Files**

Documents and data files are indexed into a vector database for semantic search and retrieval. Supported types include:

| Extension | Category |
| - | - |
| `.pdf` | Document |
| `.doc` / `.docx` | Document |
| `.ppt` / `.pptx` | Presentation |
| `.xls` / `.xlsx` | Spreadsheet |
| `.txt` | Text |
| `.md` | Text |
| `.csv` | Data |
| `.json` | Data |
| `.yaml` / `.yml` | Data |
| `.xml` | Data |

**Programming & Code Files**

Source code files are indexed and their content is made available for AI analysis. Supported languages include:

| Extension | Language |
| - | - |
| `.py` | Python |
| `.js` | JavaScript |
| `.ts` | TypeScript |
| `.java` | Java |
| `.cpp` / `.c` / `.h` | C / C++ |
| `.cs` | C# |
| `.go` | Go |
| `.rb` | Ruby |
| `.php` | PHP |
| `.swift` | Swift |
| `.kt` | Kotlin |
| `.rs` | Rust |
| `.html` | HTML |
| `.css` | CSS |
| `.sql` | SQL |
| `.sh` | Shell |

> [!NOTE]
>
> You can attach source code files directly to a conversation. The AI reads and analyzes the full code content — enabling code review, bug detection, refactoring suggestions, explanations, and more — without requiring any copy-paste.

> [!NOTE]
>
> Supported types are configured dynamically per ELITEA deployment — unsupported files are rejected with an error listing allowed extensions. Unlike images, non-image files are indexed into a vector database and retrieved via semantic search rather than sent directly to the LLM.

### File Size and Quantity Limits

| Limit | Default Value | Notes |
| - | - | - |
| Maximum attachments per message | 10 files | Applies to all file types including SVG |
| Maximum total size per message | 150 MB | Combined size of all attachments |
| Maximum individual file size | 150 MB | Applies to any single file |
| Maximum image attachments per message | 10 images | SVG files are exempt and do not count toward this limit |
| Maximum individual image size | 5 MB | SVG files are not subject to this limit |

> [!NOTE]
>
> All limits are configurable per ELITEA deployment — the values above are defaults. Raster images exceeding 5 MB are rejected client-side before sending. SVG files are exempt from the image size limit and the image count limit.

### Prerequisites

Before using attachments, ensure you have:

* **Permission Level**: Editor or Admin role within the project (required for Agent configuration)
* **Active Conversation**: An existing conversation or agent

> [!NOTE]
>
> Any user with conversation access can attach files once attachments are enabled. Editor or Admin permissions are only required for enabling attachments on Agents.

**Availability by Chat Type:**

| Context | Attachment availability |
| - | - |
| **Direct LLM / model chat** | Always enabled — **Attach Files** is active whenever no agent or pipeline is selected. |
| **Agent-based chat** | Only enabled if the agent has **Allow Attachments** toggled on in **Modules**. If not enabled, **Attach Files** is grayed out with the tooltip: *"Attachments aren't available for the selected agent or pipeline."* |
| **Pipeline-based chat** | Same rule as agents — requires `attachments` in **Modules**. |

**Enable Attachments for Agents**

Attachments must be explicitly enabled before use.

Configure attachment capabilities at the Agent level to enable file uploads in all conversations using that agent.

1. Navigate to **Agents** from the main menu
2. Select the agent to configure
3. On the **Configuration** tab, locate the **Allow attachments** toggle in **Modules** (disabled by default)
4. Click the toggle to enable attachments
5. Save the agent

**Result:** The `Attachments` module is added to the agent. The backend automatically provisions storage using the default `attachments` bucket — no additional toolkit configuration is required. When using this agent in a conversation, **Attach Files** becomes available in the **`+`** menu of the message input area.

![Enable Attachments on Agent](https://mintcdn.com/epam-a74ef051/DO68v7s2qqS2Wjw5/img/how-tos/chat-conversations/attachments/enable-attachment-agent.gif?s=e1114fcb0c4cdfb86ebf063145c06f37)

## How to Work with Attachments

### Attach Files to a Chat

Upload files directly within an active chat session without configuring the agent.

1. Open a new or existing conversation
2. Click the **`+`** button in the message input toolbar
3. Click **Attach Files** at the top of the menu
4. The file browser opens — select and confirm your files

**Result:** Attachments are immediately available. No additional setup is required.

![Enable Attachments in Chat](https://mintcdn.com/epam-a74ef051/NzZec623E5c31CCv/img/how-tos/chat-conversations/attachments/enable-attachment-chat.gif?s=cf4053accb71a6ca51925705f1d66138)

**Upload options**

**Drag and Drop**

1. Select files from your file explorer
2. Drag files directly into the message input area
3. Release to attach files

**Paste from Clipboard**

1. Copy an image to your clipboard (Ctrl+C or Cmd+C)
2. Click inside the message input area
3. Paste the image (Ctrl+V or Cmd+V) to attach

> [!NOTE]
>
> If you upload a file with the same name as an existing attachment, it is automatically renamed by appending a timestamp and file size (e.g., `image_20251106_143022_1.50KB.png`). No error is shown and both files are preserved.

### Use Attachments in Chats

When attachments are available — either because you are in a direct LLM chat or using an agent/pipeline with **Allow attachments** enabled — the **`+`** button in the message input toolbar gives access to **Attach Files**.

**Send Message with Attachments**

1. After attaching files, thumbnails appear above the message input area
2. **Type a text prompt** describing what you want the AI to do (required)
3. Click the **Send** button

   ![Chat UI with Attached Image Thumbnails](https://mintcdn.com/epam-a74ef051/NzZec623E5c31CCv/img/how-tos/chat-conversations/attachments/chat-with-attachments.gif?s=7a3cd9ae7c91ed1265e83830a638afb0)

> [!NOTE]
>
> The Send button remains disabled until you enter text. A text prompt provides context for the AI to understand how to process your attachments. When sent, each file is automatically uploaded to the default `attachments` Artifact bucket and can be viewed and managed from the **Artifacts** section in the main navigation.

### Use Agents with Attachments in Chats

The availability of **Attach Files** in the **`+`** menu is determined by the currently active participant.

* If the active agent or pipeline has **Allow attachments** enabled, **Attach Files** is active in the `+` menu
* If you switch to an agent or pipeline without attachments enabled, **Attach Files** is disabled and shows the tooltip: *"Attachments aren't available for the selected agent or pipeline."*
* In direct LLM or dummy conversations (no agent selected), **Attach Files** is always active

  ![Add Agent with Attachments](https://mintcdn.com/epam-a74ef051/NzZec623E5c31CCv/img/how-tos/chat-conversations/attachments/add-agent-with-attachments.gif?s=0fbedfe2201334e25b4afedf20ccde84)

### Edit the Last Message with Attachments

When you edit your last chat message, existing attachments remain visible and are not lost automatically.

**While editing the last message, you can:**

* Keep the existing attached files as they are
* Remove any existing attachment if you no longer want to send it
* Add a new attachment using the **attach** icon on the left side of the editor

> [!NOTE]
>
> Entering message edit mode does not remove previously attached files. Existing attachments stay visible until you explicitly remove them.

**View Attachments**

* Sent attachments display as clickable thumbnails in the chat history
* Click any thumbnail to view the full-size image or preview the file

**Download or Delete Attachments**

1. Hover over any attachment thumbnail in the chat
2. Two icons appear:

   * **Download icon**: Save the file to your local system
   * **Delete icon** (trash can): Remove the attachment

   ![Hovering over an Attachment Thumbnail](https://mintcdn.com/epam-a74ef051/NzZec623E5c31CCv/img/how-tos/chat-conversations/attachments/attachment-hover-options.gif?s=4c0a454e7199f7026e3f59a97cf2a89d)

### Delete Attachments

When clicking the delete (trash can) icon, a confirmation dialog provides two deletion options:

**Option 1: Delete from Chat Only** (default)

* Removes the thumbnail from the conversation
* Original file remains in the Artifact bucket
* File remains accessible via the Artifacts menu

**Option 2: Delete from Chat and Storage**

* Check the box: **"Also delete from attachment storage"**
* Removes the thumbnail from the conversation
* **Permanently deletes** the file from the Artifact bucket
* File cannot be recovered

![Delete Attachment Confirmation Pop-up](https://mintcdn.com/epam-a74ef051/NzZec623E5c31CCv/img/how-tos/chat-conversations/attachments/delete-attachment.gif?s=757b5304c0f931ce32ea716899a1af70)

> [!WARNING]
>
> When "Also delete from attachment storage" is checked, the file is permanently deleted from storage and cannot be recovered. Use this option carefully.

## How to Work with Non-Image Files

Non-image file attachments follow a different processing workflow than images. While images are analyzed directly by the LLM's vision capabilities, other file types are indexed for semantic search and retrieval.

**Processing Workflow:**

1. **Upload**: File is uploaded to the default `attachments` bucket
2. **Indexing**: File content is automatically extracted and indexed into a vector database
3. **Retrieval**: When you query, relevant content is retrieved through semantic search

![Non-Image Files Processing Workflow](https://mintcdn.com/epam-a74ef051/DO68v7s2qqS2Wjw5/img/how-tos/chat-conversations/attachments/non-image-files.gif?s=8822e085a958c5e81a00de8ddd50ae62)

**Key Differences from Images:**

| Feature | Images | Non-Image Files |
| - | - | - |
| Processing | Sent directly to LLM | Indexed in vector DB |
| Analysis | Real-time vision analysis | Semantic search retrieval |
| Query type | Visual analysis | Content-based search |
| Token usage | Per image | Per retrieved chunk |

> [!TIP]
>
> Since content is retrieved through semantic search, specific queries that describe the information you're looking for will yield better results than general summarization requests.

**Shared Collection Behavior**

All non-image attachments are indexed into the same storage collection in the default `attachments` bucket.

**Implications:**

* Search results may include content from previously attached files (if using the same toolkit)
* Queries might retrieve information from multiple uploaded files
* Results may include content you didn't intend to search

**Recommendations:**

1. **Be specific in queries** to avoid retrieving irrelevant content from other files
2. **Include context** in queries to help narrow down relevant content
3. **Reference filenames** when querying if you need content from a specific file

**Usage Tips**

> **Structure your queries effectively**
>
> Instead of asking "What does the file say?", ask "What are the recommended security practices mentioned in the uploaded security guidelines?"

> **Include context in your prompt**
>
> Reference the file type or subject: "In the uploaded project plan, what are the Q2 milestones?"

> **Query for specific sections**
>
> Ask for particular information: "Find all mentions of API rate limits in the uploaded documentation"

> **Use keywords from your files**
>
> If you know specific terms appear in your files, include them in queries to improve retrieval accuracy

## FAQ

> **Where are my attached files stored?**
>
> All attachments are stored in the default `attachments` bucket. You can view and manage these files from the **Artifacts** menu in the main navigation.

> **How long are files stored?**
>
> By default, new Artifact buckets have a 30-day retention period. Files older than the retention period are automatically deleted. You can view and modify retention periods from the **Artifacts** page.

> **Can I use attachments with multiple agents in one conversation?**
>
> Yes. In conversations, all attachments are saved to the default `attachments` bucket. All agents participating in that conversation can access the chat history, including attachments. Which agents can process attachments depends on their individual configuration — only agents with **Allow attachments** enabled can actively use attached files.

> **Can I recover a deleted attachment?**
>
> No. Deletion is permanent. If you delete a file from the Artifacts bucket or use the "Also delete from attachment storage" option in chat, it cannot be recovered.

> **Why can't I send a message with only an attachment and no text?**
>
> The system requires a text prompt to provide context about how the AI should interpret or process the attachment(s). The Send button activates only after you enter text.

> **How many tokens does an image consume?**
>
> Token consumption varies by LLM provider:
>
> * **Claude (Anthropic)**: Fixed number of tokens per image (consult model documentation)
> * **GPT (OpenAI)**: Varies based on image size and resolution
>
> Check your LLM provider's documentation for specific token costs.

> **What happens when I attach the same filename twice?**
>
> Duplicate filenames are handled automatically. The system renames the new file by appending a timestamp and file size (e.g., `image_20251106_143022_1.50KB.png`). Both files are preserved in the bucket with distinct names — no error is shown and no data is overwritten.

> **Can I use attachments in Pipeline conversations?**
>
> Yes. Pipelines have the **Allow attachments** toggle in **Modules**. When enabled, the toggle adds `attachments` to the pipeline's modules and also adds an `input_attachments` state variable to the pipeline YAML. Once enabled, the paperclip icon becomes active when using that pipeline in a conversation.

## Troubleshooting

> **File size exceeds image limit**
>
> **Error:** Image is rejected when attaching
>
> **Cause:** The image exceeds the 5 MB per-image size limit (SVG files are exempt).
>
> **Solution:**
>
> 1. Compress or resize the image below 5 MB
> 2. For SVG files, the size limit does not apply
> 3. Re-attach the file

> **Attach Files is disabled or shows a tooltip in the + menu**
>
> **Symptom:** Clicking `+` shows **Attach Files** with the tooltip *"Attachments aren't available for the selected agent or pipeline."*
>
> **Cause:** The active agent or pipeline does not have **Allow attachments** enabled.
>
> **Solution:**
>
> 1. Enable **Allow attachments** on the agent via its **Configuration** tab (see Enabling Attachments above)
> 2. Verify you have the required permissions to edit the agent configuration
> 3. Contact a project administrator if permissions are insufficient

> **Unexpected filename in chat after upload**
>
> **Symptom:** Attached file appears with a different name than the original (e.g., `image_20251106_143022_1.50KB.png`)
>
> **Cause:** A file with the same name was already attached. The system automatically renames duplicates with a timestamp and file size suffix to avoid overwriting existing files.
>
> **Solution:** This is expected behavior. Both files are preserved. Use unique filenames if you need to distinguish uploads easily.

> **Attachment visible in chat but not found in Artifacts**
>
> **Symptom:** Thumbnail appears in chat, but file is missing from Artifacts menu
>
> **Possible Causes:**
>
> * File was deleted directly from the Artifacts page
> * Retention period expired and file was auto-deleted
>
> **Solution:** Files deleted from Artifacts cannot be recovered. Re-upload if needed.

> **Cannot delete attachment with Also delete from attachment storage option**
>
> **Error:** Deletion fails when "Also delete from attachment storage" is checked
>
> **Possible Causes:**
>
> * File was already deleted from the bucket via the Artifacts page
>
> **Solution:**
>
> 1. Uncheck "Also delete from attachment storage"
> 2. Delete from chat only

> **Maximum attachment limit reached**
>
> **Error:** Cannot attach more files to a message
>
> **Cause:** Attempting to attach more than the maximum number of files per message (default: 10)
>
> **Solution:**
>
> 1. Remove some attachments to stay within the limit
> 2. Send multiple messages if needed
> 3. Combine related content into fewer files when possible

> **Maximum image attachment limit reached**
>
> **Error:** Toast warning — `Maximum N image attachments allowed`
>
> **Cause:** The number of non-SVG images attached would exceed the image attachment limit (default: 10). SVG files do not count toward this limit because they are processed as documents.
>
> **Solution:**
>
> 1. Remove some image attachments
> 2. Send images across multiple messages

> **Total message size exceeds limit**
>
> **Error:** Message fails to send due to total attachment size
>
> **Cause:** Combined size of all attachments exceeds 150 MB
>
> **Solution:**
>
> 1. Reduce number of attachments
> 2. Compress images or files
> 3. Send multiple messages with fewer attachments each


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.