Bot API reference
The constraints, with their numbers
A reference to the Telegram Bot API limits that change what can be built: the send ceilings, the file size caps, the 64-byte and 64-character payload limits, the signature validation a Mini App requires, and the windows in which a message can be edited, deleted or refunded. Each page carries the exact figure and a working example.
Telegram Bot API limits and mechanics: what this section covers
- Reference pages
- 50 planned, each with an exact figure and runnable code
- Scope
- Bot API limits and mechanics only — not a tutorial
- Soft limits
- Marked as approximate where Telegram does not publish a fixed number
- Verification
- Every figure is checkable against Telegram's own documentation
As of 2025-10-01, Telegram Bot API 13.4
How to read this reference
Most Bot API questions have an exact answer, and almost none of the pages that come up when you search for one will give it to you. The official documentation is a complete API reference and is deliberately not a guide to consequences; the tutorials repeat the happy path. What is missing in both is the number and what it does to a design — that a broadcast to forty thousand people takes twenty-two minutes, that an inline button carries sixty-four bytes and not a character more, that a message can be deleted for forty-eight hours and then never.
These pages fill that gap and nothing else. Each one takes a single limit or mechanic, states it in the first sentence with its units, explains what it changes about a build, and shows the code that handles it correctly. They are short on purpose. A reference page that has to be read twice has failed at the job of being a reference.
They are also the pages this studio would rather be judged on than any portfolio. A limit is checkable against Telegram's own documentation in under a minute, and anyone who has built against this API can tell from a paragraph whether the person writing had. That is a slower way to establish that you know what you are doing than a wall of client logos, and a considerably more durable one.
Where a limit is soft rather than published — the send rate is the clearest case — that is stated rather than smoothed over. Building against a number Telegram describes as approximate, as though it were a contract, is a specific way to ship something that works in testing and fails at the volume that matters.
Rate limits and delivery
The ceilings that decide how fast anything can happen, and the delivery guarantees that decide whether it happens twice. Most production incidents in this trade start in this group.
The limit that turns a forty-thousand-subscriber campaign into a twenty-two minute operation is
A far tighter and entirely separate budget applies inside a single group, described in
What the server sends back when either ceiling is exceeded, and why a generic backoff makes it worse, is in
How updates reach a bot at all, and which of the two belongs in production, is covered in
An unvalidated webhook accepts fabricated updates from anyone, which is the subject of
Why the same update can legitimately arrive twice, and what that does to a payment handler, is in
What a successful send actually proves, which is less than most stakeholders assume, is set out in
The single unambiguous per-recipient delivery signal the API offers is documented in
About this reference
Why not just read the official Bot API documentation?
You should, and these pages link into it. The official reference documents what each method accepts and returns, which is exactly what a reference should do and is not the same as telling you that the send ceiling makes a timed broadcast impossible, or that a 64-byte callback payload cannot hold a date and a practitioner id. These pages are about the consequences.
Are these limits stable, or do they change?
The structural ones — payload sizes, file caps, the deletion window — have been stable for years. The rate ceilings are described by Telegram as approximate and are enforced adaptively, which is why they are presented here as figures to design under rather than constants to build against. Changes that matter are tracked on the changelog page.
Is the code on these pages production code?
It is the shape of production code, reduced to the point being made. Error handling that is the subject of a page is shown in full; error handling that is not is elided so the example stays readable. Where something is genuinely load-bearing — the constant-time comparison on init data, the conditional write on an allocation — it is written out rather than summarised.
Which of these actually cause problems in practice?
In rough order: the send ceilings, at-least-once delivery, the 64-byte callback payload, and the pre-checkout timeout. The first two produce incidents at scale, the third produces a redesign midway through a build, and the fourth produces failed payments that look like a payment provider problem and are not.
Related reading
Every build in this catalogue is shaped by the limits documented here, and is listed in the priced catalogue.
Where these constraints make a different platform the better answer, that case is argued in the comparisons.
For the surface where signature validation and viewport behaviour matter most, see the Mini Apps section.
Third-party quotas often bind before Telegram's do, and each one is documented in the integration pages.