# Telegram large-file downloads for transcription

Use when a Telegram user says they attached audio/video but Hermes receives an empty or file-less message, or logs show `Failed to cache audio` / `File is too big`.

## Cause

This is usually a Telegram Bot API transport limit, not a transcription/STT failure. With the public Telegram Bot API, bot `getFile` downloads are capped around 20 MB. Hermes may receive the Telegram update, then fail while caching the media, so the agent sees an empty user message.

## Immediate user-facing response

Do not imply the user failed to attach the file. Say:

- the attachment likely existed;
- Telegram Bot API refused the bot-side download because the file is too large;
- STT can still work if the file arrives via another route.

Ask for one of:

- Google Drive / Dropbox / Yandex Disk link with public viewer access;
- compressed speech audio, e.g. MP3 mono 64–96 kbps;
- split parts below the bot download cap.

## Durable fix: local Telegram Bot API server

Hermes' Telegram adapter supports a locally hosted `telegram-bot-api` server. When configured via Telegram `extra.base_url`, Hermes treats the download cap as ~2 GB instead of the public Bot API cap.

Config shape:

```yaml
telegram:
  base_url: "http://127.0.0.1:8081/bot"
  base_file_url: "http://127.0.0.1:8081/file/bot"
  local_mode: true
```

Notes:

- The local Bot API server requires Telegram application credentials: `api_id` and `api_hash` from https://my.telegram.org/apps.
- Do not add `base_url` until the local server is actually running; otherwise the Telegram gateway will break.
- With `local_mode: true`, PTB reads downloaded files from the local server filesystem path, so Hermes and the Bot API server must run on the same machine or share the relevant filesystem.
- Store tokens and API hashes only in environment/config as secrets; never paste them into transcripts, memories, or user-facing summaries.

## Verification

After enabling, restart the gateway and send a test audio/video larger than 20 MB. Confirm the gateway logs no longer contain `File is too big` and that the agent receives a media path or transcription text.