Using PDF and attachment support with AI bots

Documentation Site Management
, ,
1

:bookmark: This guide explains how to enable and use native PDF and document attachment support when interacting with AI bots in Discourse. Users can upload PDFs and other documents directly in conversations with AI agents.

:person_raising_hand: Required user level: Administrator

Summary

Discourse AI now supports native attachment handling, allowing users to upload PDFs and other document types directly when conversing with AI bots. The AI can read and understand the content of these attachments, enabling use cases like document analysis, summarization, and question-answering based on uploaded files.

This feature requires:

  • Allowed attachment types configured on the LLM
  • An agent that has vision enabled (this controls whether uploads are included in messages)
  • The file extension to be authorized in your site’s upload settings

Supported providers

Native attachment support works with models from the following providers:

  • Anthropic (Claude models)
  • AWS Bedrock (Claude models via Bedrock)
  • Google (Gemini models)
  • OpenAI (GPT models)
  • Azure (OpenAI-compatible models)
  • OpenRouter (OpenAI-compatible models)

Each provider handles attachments differently at the API level, but Discourse AI manages this automatically. Keep in mind that different provider implement different levels of support for various attachment types.

Supported attachment types

The following document types can be configured for AI processing:

Type Extensions
PDF pdf
Plain text txt
Microsoft Word doc, docx
Rich Text Format rtf
HTML html, htm
Markdown md, markdown

:information_source: Images are handled separately through the “Vision enabled” setting and don’t require attachment type configuration.

Configuration

Step 1: Authorize file extensions for upload

Before users can upload attachments, ensure the file extensions are authorized in your site settings.

  1. Navigate to Admin → Files
  2. Find the authorized extensions setting
  3. Add the extensions you want to allow (e.g., pdf|txt|docx)

Step 2: Configure the LLM model

  1. Navigate to Admin → Plugins → Discourse AI → LLMs
  2. Select the LLM model you want to configure (or create a new one)
  3. In the Allowed attachments field, select or type the file extensions you want the model to accept (e.g., pdf, txt, docx)

llm configuration showing pdf / txt selection in allowed attachments
llm configuration showing pdf / txt selection in allowed attachments622Ă—235 14.2 KB

:warning: If you leave the “Allowed attachments” field blank, document attachments will be disabled for that model. Images are controlled separately via the “Vision enabled” toggle.

Step 3: Configure the agent

  1. Navigate to Admin → Plugins → Discourse AI → Agents
  2. Select or create an agent
  3. Ensure Vision enabled is turned on — this controls whether uploads (both images and documents) are included in messages sent to the LLM
  4. Set the Default model to an LLM that has attachments configured

How it works

When a user uploads a document in a conversation with an AI bot:

  1. The document is uploaded to Discourse using standard upload handling
  2. Discourse AI encodes the document content (base64)
  3. The encoded content is sent to the LLM along with the user’s message
  4. The LLM processes both the text message and document content
  5. The AI responds based on the combined context

image
image1091Ă—1102 149 KB

Technical details

  • Documents are encoded as base64 and sent inline with the request
  • Each provider receives attachments in their native format:
    • Anthropic: Uses document type with base64 source
    • Gemini: Uses inlineData format
    • OpenAI (Chat Completions API): Uses file type with file_data containing the base64 content
    • OpenAI (Responses API): Uses input_file type with file_data containing the base64 content
  • File size limits are governed by your site’s max attachment size kb setting

Use cases

Native attachment support enables several workflows:

  • Document analysis: Upload contracts, reports, or research papers for the AI to summarize or answer questions about
  • Content review: Have the AI review and provide feedback on draft documents
  • Data extraction: Extract specific information from uploaded documents
  • Translation assistance: Upload documents in one language and discuss content or request translations
  • Technical support: Users can upload log files or configuration files for troubleshooting assistance

Limitations

  • File size: Attachments are limited by your site’s upload size settings and LLM vendor
  • Provider support: Attachment support requires a provider dialect that handles documents (Anthropic, AWS Bedrock, Google, OpenAI, Azure, and OpenRouter)
  • Agent vision requirement: The agent must have “Vision enabled” turned on for uploads to be included in messages
  • Extension matching: The file extension must be both authorized for upload on your site and allowed in the LLM’s attachment types configuration
  • Results vary: Since LLM vendors and LLMs are processing the files cost / accuracy and results will vary. Anthropic tends to use more tokens for analysis than either OpenAI or Google.
  • Enable caching: For Open AI be sure to use responses API which offers more consistent support for caching (when thinking enabled) for Anthropic models you may need to enable caching explicitly in the LLM config. This can be particularly important when having multi turn conversations.

Troubleshooting

Attachments aren’t being processed

  1. Verify the file extension is in your site’s authorized extensions setting
  2. Confirm the file type is listed in the LLM’s “Allowed attachments” setting
  3. Ensure the agent has “Vision enabled” turned on and uses a properly configured LLM

Upload fails

  • Check your max attachment size kb setting
  • Verify the file extension is authorized
  • Very large PDFs may not be supported, each LLM vendor has differing maximum upload sizes.

AI doesn’t understand the document

  • Ensure you’re using a model that supports document understanding
  • Try a more capable model (e.g., Claude Sonnet 4.5, GPT-5.1, Gemini Pro 3)

FAQs

Can users upload multiple documents in one message?
Yes, users can include multiple attachments in a single message, and the AI will have access to all of them.

Does this work in chat as well as PMs?
Yes, attachment support works in both private messages with AI bots and in chat direct messages, provided the agent is configured for those interaction methods.

Is this different from RAG uploads on agents?
Yes. RAG uploads are documents added by administrators to an agent’s knowledge base, which are indexed and searched. Native attachment support allows end users to upload documents during conversations for immediate analysis without indexing.

What happens to uploaded documents?
Documents are processed according to your site’s standard upload handling and retention policies. They’re stored as regular Discourse uploads.

Additional resources

4 Likes
PDF support in Discourse AI (RAG)
Native PDF and attachment support in Discourse AI