Developers building high-performance Telegram bots often hit a wall with the standard cloud API. While the official interface at api.telegram.org is convenient, it imposes strict limits on file sizes and webhook configurations that can hinder complex automation projects. By deploying a self-hosted Telegram Bot API server, you can bypass these constraints, significantly improving performance and flexibility for media-heavy applications.
Why Self-Host the Telegram Bot API?
The primary motivation for running your own server is the removal of file size restrictions. The standard API limits uploads to 50 MB and downloads to 20 MB. In contrast, a local server allows you to handle files up to 2 GB (2000 MB) for both uploading and downloading. This is critical for bots that process large videos, audio files, or other substantial media content.
Beyond file limits, a local server reduces network latency. Since requests are handled by your own infrastructure before being forwarded to Telegram, the round-trip time is minimized, especially if your bot and API server are geographically close or on the same network. Additionally, the local server supports the file:// URI scheme for uploads, eliminating the need to transmit files via HTTP requests entirely.
Key Advantages of the Local Server
Flexible Webhook Configuration
The standard API requires HTTPS and restricts webhooks to specific ports (443, 80, 88, or 8443). A self-hosted server running in local mode allows you to use plain HTTP for webhooks on any IP address and any port. This flexibility simplifies development and testing environments where setting up TLS certificates is cumbersome.
High-Concurrency Support
For high-load systems, the local server offers a significant boost in capacity. The max_webhook_connections parameter can be raised up to 100,000, compared to the standard API’s limit of 100. This makes local deployment ideal for bots that need to handle a massive volume of concurrent updates.
Unlike the standard Bot API, which limits uploaded file size to 50 MB, the local server allows working with files up to 2000 MB (2 GB).
Direct File Access
When running in local mode, the getFile method returns the absolute local path to the file rather than a URL. This means your bot application can read files directly from the disk, provided it has access to the server’s data directory, such as through a shared Docker volume. This eliminates the overhead of downloading files over the network.
Setting Up the Server with Docker
Deploying the Telegram Bot API server is straightforward using Docker and Docker Compose. This approach ensures a reproducible environment and simplifies updates. Before starting, ensure you have Docker installed and have obtained your API ID and API Hash from my.telegram.org.
Configuration Steps
First, create a .env file containing your TELEGRAM_API_ID and TELEGRAM_API_HASH. Next, define your services in a docker-compose.yml file. The configuration must include the --local flag in the command arguments. Without this flag, the server behaves exactly like the cloud API, retaining all standard limitations.
The Dockerfile should be built in two stages: one for compiling the binary from the official tdlib/telegram-bot-api repository and another for the runtime environment. Using Ubuntu 24.04 as the base image is recommended, along with necessary dependencies like libssl3t64. It is crucial to run the server as an unprivileged user and to pin the build to a specific commit hash for reproducibility.
Important Security and Protocol Considerations
Security is paramount when self-hosting. The Bot API server accepts requests using a single bot token without additional authentication checks. Therefore, you must never expose the server port to the public internet. In Docker Compose, bind the port to 127.0.0.1 only. If your bot application runs in the same Compose project, it can communicate with the API server via the internal service name, eliminating the need to publish the port entirely.
Protocol compatibility is another common pitfall. The local server only supports HTTP/1.0 and HTTP/1.1. If your client library or proxy attempts to use HTTP/2, the server will respond with a 505 HTTP Version Not Supported error. Ensure that your client configuration explicitly sets the HTTP version to 1.1. If you are using a reverse proxy like Nginx, Caddy, or HAProxy to provide HTTPS access from the outside, configure the proxy to communicate with the Bot API server using HTTP/1.1.
Migrating from the Cloud API
If your bot was previously using the cloud API, you must log it out before switching to the local server. Use the logOut method via a curl request to the standard API endpoint. This step is essential to prevent updates from continuing to flow to Telegram’s servers. Note that after logging out, you cannot return the bot to the cloud API for at least 10 minutes. If you need to move the bot to a different local server, call deleteWebhook and close the connection on the old server first.
Conclusion
Self-hosting the Telegram Bot API is a powerful solution for developers who need to handle large files, reduce latency, or configure flexible webhooks. By using Docker, you can deploy a secure, reproducible instance that runs entirely on your infrastructure. While the standard API remains suitable for small projects with modest file requirements, the local server unlocks advanced capabilities for complex, high-load automation systems. Always remember to secure your server by keeping it private and managing protocol versions correctly to avoid common connectivity errors.