Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ragnarok22/telegram-bot-api-docker/llms.txt

Use this file to discover all available pages before exploring further.

​
Why Migrate to Self-Hosted?

Migrating from api.telegram.org to a self-hosted Telegram Bot API server gives you:
  • Direct file access: Download and serve files without size limits when using local mode
  • Better performance: Reduced latency by hosting the API server closer to your application
  • Custom configuration: Control webhook connections, log verbosity, and other server parameters
  • Network isolation: Keep bot traffic within your infrastructure for enhanced security

​
Prerequisites

Before starting the migration, ensure you have:
  • A running instance of the self-hosted Telegram Bot API server
  • Your bot token ready
  • Access to modify your bot client configuration
  • Network connectivity from your bot application to the self-hosted server
To guarantee your bot receives all updates, you must properly deregister from api.telegram.org before switching servers. Skipping this step may result in lost updates.

​
Migration Steps

1

Call logOut on the official API

Before switching to your local server, deregister your bot from api.telegram.org by calling the logOut method:
curl https://api.telegram.org/bot<YOUR_BOT_TOKEN>/logOut
This ensures Telegram’s servers stop routing updates to the official API endpoint and prepares your bot for the new server.
Wait for a successful response before proceeding to the next step. The response should indicate that the bot was successfully logged out.
2

Update your bot client configuration

Modify your bot application to point to your self-hosted server instead of api.telegram.org.Replace:
https://api.telegram.org/bot<TOKEN>/
With:
http://your-server:8081/bot<TOKEN>/
Example configuration changes:
from telegram.ext import ApplicationBuilder

app = ApplicationBuilder().token("YOUR_BOT_TOKEN").base_url(
    "http://your-server:8081/bot"
).build()
3

Handle local mode file paths

If your server is running with TELEGRAM_LOCAL=true, the getFile response will contain absolute file paths instead of relative paths.
When local mode is enabled, ensure your bot application can handle absolute file paths in getFile responses. The file path will point directly to the file on the server’s filesystem.
Example response difference:Without local mode:
{
  "file_id": "AgACAgIAAxkBAAI...",
  "file_path": "photos/file_1.jpg"
}
With local mode:
{
  "file_id": "AgACAgIAAxkBAAI...",
  "file_path": "/data/bot123456/photos/file_1.jpg"
}
Local mode should only be enabled in trusted environments with proper network isolation. See the Configuration documentation for security considerations.
4

Test the migration

Verify that your bot is working correctly with the self-hosted server:
# Test basic connectivity
curl http://your-server:8081/bot<TOKEN>/getMe

# Check webhook status (if using webhooks)
curl http://your-server:8081/bot<TOKEN>/getWebhookInfo

# Send a test message to your bot
# Verify it responds correctly
Monitor your application logs and the server logs at /data/logs/telegram-bot-api.log to ensure everything is functioning properly.

​
Rollback Procedure

If you need to revert to api.telegram.org, follow these steps:
1

Log out from the self-hosted server

curl http://your-server:8081/bot<TOKEN>/logOut
2

Update client back to official API

Change your bot client configuration back to:
https://api.telegram.org/bot<TOKEN>/
3

Restart your bot application

Restart your bot to reconnect to the official API.

​
Common Issues

  • Updates not arriving: Ensure you called logOut on the previous server before switching
  • Connection refused: Verify firewall rules and that the self-hosted server is accessible from your bot application
  • File download errors: Check if your application properly handles the file path format based on whether local mode is enabled
  • Certificate errors: If using HTTPS, ensure SSL/TLS certificates are properly configured

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us