YAML Metadata Warning:empty or missing yaml metadata in repo card
Check out the documentation for more information.
telegram-buffer
Backend for the telegram-buffer Claude skill. It reads the private chat with
the buffer bot as a user session via Telethon, so the Telegram Bot API's
20 MB getFile ceiling does not apply. The user-session ceiling is 2 GB
(4 GB on Telegram Premium).
FastAPI, Docker, listens on $PORT (default 7860).
Endpoints
Every endpoint except / requires ?key=<BUFFER_KEY>.
| Endpoint | Purpose |
|---|---|
GET / |
Unauthenticated liveness ping. Health-check and keep-alive target. |
GET /health |
Config check plus which Telegram account the session belongs to |
GET /fetch |
Scan back to the newest incoming cleared, return everything after it as a manifest, then post a fresh cleared |
GET /file/{id} |
Stream that message's media straight from Telegram |
GET /clear |
Post the cleared watermark by hand |
GET /login/start |
One-time: request a Telegram login code |
GET /login/finish |
One-time: exchange the code for a session string |
Watermark protocol
The bot posts the literal text cleared into the chat after any fetch that
returned messages. /fetch walks the chat newest-first and stops at the most
recent incoming message whose text is exactly cleared; everything newer is
returned, oldest first. If no watermark exists inside the scan window, /fetch
sets one and returns nothing, so a first run can never dump the whole chat
history. ?all=1 overrides that for the deliberate first run.
Nothing touches disk
/fetch reads metadata only. /file/{id} re-resolves the message by id and
streams the bytes through with iter_download, so a 1.5 GB video moves through
a 512 MB container without buffering, and no state is lost when a free-tier host
restarts or spins down.
Environment
BUFFER_KEY, TG_API_ID, TG_API_HASH, TG_PHONE, TG_BOT_TOKEN,
TG_BOT_USERNAME, TG_SESSION. Optional: PUBLIC_URL (forces the host used in
manifest URLs), SCAN_LIMIT (default 400), WATERMARK_TEXT (default cleared).
Free-tier note
On Render's free plan the service sleeps after 15 minutes of no inbound traffic
and takes about a minute to wake. Ping / every 10 minutes to keep it warm;
730 h/month of uptime fits inside the 750 free instance-hours.