Albums, buttons and captions: combinations Telegram refuses

The Bot API documentation describes methods but says little about which combinations simply do not work. Here is what live calls reveal.

Buttons and albums

One media item with buttons — fine. An album of several photos with buttons — the request goes through, the response is successful, and there are no buttons in the chat. Telegram silently drops them.

So your code has to check: either buttons or an album. The only way around it is sending the album first and the text with buttons after.

Album homogeneity

Photos and videos group together in one album. Documents group only with documents, audio only with audio. Mixing a document with a photo is rejected outright.

Voice notes and video notes

A voice message and a video note always go as their own message. They cannot join an album or accompany other media.

Captions on albums

The caption shows on the first item only, and its limit is the same 1024 characters. Long text under an album has to travel as a second message.

Practical takeaway

Encode these rules once into a check that fires when the file is attached, not when the post is published. People need to learn “this is not allowed” before writing the post, not at the moment it should have gone out.

That is what we did: an invalid combination is explained immediately, and long text with an album goes out as a rich message. See features.