Telegram Bot API server
github.com · Debrid · 1 record · JSON
Telegram Bot API server (self-hosted, --local mode) Debrid
caveatany-phoneno cardphoneDper-object-cap
| 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 |
| 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. |
| 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 |
| 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. |
| 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). |
| 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 the client 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 rung | documented The limit sentences are on the project README and the Bot API page, both read today. A measured rung needs a 2 GB upload through a running instance; that was not done. |
| Checked | 2026-10-24 (live); stale on 2026-11-23 |
| 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 | 'If the bot is logged in on more than one server simultaneously, there is no guarantee that it will receive all updates.' |
| 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 |