Migrating from api.telegram.org

Switch your bot from the official Telegram Bot API to your self-hosted server

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:

   Python (python-telegram-bot)

   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

• Learn about moving between self-hosted servers
• Review environment variables for server configuration
• Configure port mappings for your deployment