My girlfriend tried to set a video avatar on her Telegram profile last month. Fresh clip from her iPhone 15, under ten seconds, looked great. Telegram accepted the upload, spun for a moment, then did nothing. No error message, no broken thumbnail. Nothing.
I pulled the file onto my laptop and ran ffprobe. Codec: hevc. That was the whole bug. iPhones have recorded HEVC (H.265) by default since iOS 11, and Telegram's video avatar pipeline only takes H.264. Instead of saying so, it silently drops the file.
One ffmpeg command fixed her avatar. Then I figured other people hit this every day, so I wrapped the command in a Telegram bot. This post is the build log: the spec Telegram actually enforces, the ffmpeg pipeline, and the aiogram 3 code that glues it together.
What Telegram actually accepts
There is no single doc page listing the video avatar requirements, so I collected them through testing and scattered API notes:
