Telegram Bot API server (self-hosted, --local mode)
- Free allowance
- No fee to Telegram. The cost is a host: the server must run somewhere with outbound internet.
- Verdict
- self-hosted, last resortverdict qualifies-with-caveat: usable, with a named limit or an unprobed read path. Self-hosted options are listed last, because this site is for users who have no hardware.
- Cost
- not stated
- Identity
- any-phoneno card, phone required
- Binding limit
- per-object-cap2000 MB per upload in --local mode (50 MB on api.telegram.org)
- Evidence
- documented4 sources; a first-party page was read and the sentence quoted
- Freshness
- stale on 2026-11-23checked 2026-10-23 (live); stale on 2026-11-23
| Free tier | No fee to Telegram. The cost is a host: the server must run somewhere with outbound internet. 'The only mandatory options are --api-id and --api-hash.' unit none; metered on none; the account's own 2 GB free / 4 GB Premium per-file ceiling still applies to a user session; this record is about the bot gateway |
|---|---|
| Price | none stated |
| Limits |
Download has no size limit in local mode; upload does. The asymmetry is the reason a mirror bot can pull a 2 GB file but still split anything above 2 GB. |
| Binding | per-object-cap At 1 TiB/month this still fails first: no object above 2000 MB can be sent, so the month is 512+ objects at best. Flood control is nowhere near binding (see telegram-uploadbot). |
| Identity | any-phone my.telegram.org issues api_id/api_hash to a Telegram account, and a Telegram account is registered to a phone number. No card and no email are required for the app registration. |
| Egress | No separate charge from Telegram. The host's outbound bandwidth is the part that is metered, by whoever runs the host. free allowance: none published |
| Per-object cap | In local mode the server 'Upload[s] files up to 2000 MB' and 'Download[s] files without a size limit.' |
| Retention | Not applicable: a gateway. Bytes live in the chat they were sent to, not on the server. |
| Interface | rest HTTP JSON API. 'By default the Telegram Bot API server is launched on the port 8081, which can be changed using the option --http-port.' The server 'accepts only HTTP requests, so a TLS termination proxy needs to be used to handle remote HTTPS requests.' endpoint: http://127.0.0.1:8081 (default --http-port) |
| Tooling | Docker image or CMake build of tdlib/telegram-bot-api; any Bot API client library can be pointed at it. The state-of-the-art in-the-wild user is the Torrs bot, which runs the server to lift its own 50 MB ceiling. |
| Composes with | Raises a bot from 50 MB per upload and 20 MB per download to 2000 MB and unlimited, so a 2 GB file in a channel becomes retrievable by a script; needs a VM plus a TLS proxy, which a free compute tier supplies. |
| Reliability | One server per bot at a time: moving a bot requires logOut from api.telegram.org first, or updates are silently lost ('If the bot is logged in on more than one server simultaneously, there is no guarantee that it will receive all updates.'). |
| Notes | Abandon this if Telegram ships the local-mode upload cap below 2 GB, or if the 2000 MB figure disappears from the README without a replacement. This is software a user must run, not a hosted service; it is recorded because it is the only documented way to make a bot a 2 GB path, and because hosted leech bots visibly depend on it. |
| Evidence note | documented The limit sentences are on the project README and the Bot API page, both read. A measured rung needs a 2 GB upload through a running instance; that was not done. |
| Parsed numbers |
|
Evidence 4
| date | source | what it proved |
|---|---|---|
| 2026-10-23 | github.com/tdlib/telegram-bot-api | 'To enable Bot API features not available at https://api.telegram.org, specify the option --local. In the local mode the Bot API server allows to: Download files without a size limit. Upload files up to 2000 MB.' and the mandatory --api-id/--api-hash sentence |
| 2026-10-23 | github.com/tdlib/telegram-bot-api | part of the text of Reliability, above |
| 2026-10-23 | core.telegram.org/bots/api | 'If you switch to a local Bot API server, your bot will be able to: Download files without a size limit. Upload files up to 2000 MB.' plus 'The majority of bots will be OK with the default configuration, running on our servers.' |
| 2026-10-23 | core.telegram.org/api/limits | 'Page not found' on 2026-10-23, and the Wayback capture 20250718224518 of the same URL is the same 'Page not found' - there is no limits page to cite, so flood numbers come from bots/faq and api/errors |