Bug description

When a user sends an image to Hermes via Telegram as a document (instead of as a normal photo), Hermes rejects certain image formats such as .webp with:

Unsupported document type '.webp'. Supported types: .cfg, .csv, .docx, .ini, .json, .log, .md, .pdf, .pptx, .toml, .txt, .xlsx, .xml, .yaml, .yml, .zip

This is confusing because .webp is a valid image format and should be processed through the normal image/vision pipeline.

Steps to reproduce

1. Use the Telegram gateway.
2. Send a .webp image as a document/file (not as a Telegram photo).
3. Observe that Hermes responds with: Unsupported document type '.webp'...

Expected behavior

Telegram image documents such as:

• .jpg
• .jpeg
• .png
• .webp
• .gif

should be treated as images, cached into the image cache, and routed through the same image analysis path as normal Telegram photos.

Actual behavior

The Telegram adapter currently checks document extensions only against SUPPORTED_DOCUMENT_TYPES and SUPPORTED_VIDEO_TYPES.

If the uploaded file is an image document like .webp, it falls through to the unsupported-document branch.

Root cause

In gateway/platforms/telegram.py, the msg.document branch:

• resolves extensions from filename / MIME type
• handles video documents
• handles generic supported documents
• but does not have a dedicated branch for image documents

As a result, image files sent as Telegram documents are rejected unless they happen to be uploaded as msg.photo.

Proposed fix

Add a dedicated image-document mapping and branch in the Telegram adapter.

Example approach

In gateway/platforms/telegram.py:

1. Introduce something like:

SUPPORTED_IMAGE_DOCUMENT_TYPES = {
    ".jpg": "image/jpeg",
    ".jpeg": "image/jpeg",
    ".png": "image/png",
    ".webp": "image/webp",
    ".gif": "image/gif",
}

1. In the msg.document handling path:

• resolve image extensions from MIME type as well
• if ext in SUPPORTED_IMAGE_DOCUMENT_TYPES:
  • download bytes
  • cache via cache_image_from_bytes(...)
  • set:
    • event.media_urls
    • event.media_types
    • event.message_type = MessageType.IMAGE
  • enqueue through the photo/image path instead of the document path

1. Update the unsupported-type message so the supported image-document extensions are included in the reported list.

Notes

I locally verified that this approach fixes .webp uploads sent via Telegram as documents and routes them correctly into image analysis.

Relevant area:

• gateway/platforms/telegram.py
• current unsupported-document branch around the msg.document handling logic

Environment

• Hermes Agent v0.12.0
• Telegram gateway