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 personas.

: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:

  • An LLM model with vision enabled
  • Allowed attachment types configured on the LLM
  • A persona that supports vision
  • 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)
  • Google (Gemini models)
  • OpenAI (GPT 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. Enable Vision enabled - this is required for attachment support
  4. 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 persona

  1. Navigate to Admin → Plugins → Discourse AI → AI Personas
  2. Select or create a persona
  3. Ensure Vision support is enabled for the persona
  4. Set the Default model to an LLM that has vision and 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: Uses 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: Only Anthropic, Google, and OpenAI models currently support attachments
  • Vision requirement: The LLM must have vision capabilities enabled
  • 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. Check that the LLM has “Vision enabled” turned on
  3. Confirm the file type is listed in the LLM’s “Allowed attachments” setting
  4. Ensure the persona has vision support enabled 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 persona is configured for those interaction methods.

Is this different from RAG uploads on personas?
Yes. RAG uploads are documents added by administrators to a persona’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
Site Management Index
PDF support in Discourse AI (RAG)
Native PDF and attachment support in Discourse AI