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.

​
Migration Scenarios

You may need to move your bot between self-hosted servers in several situations:
  • Infrastructure changes: Migrating to new hardware or cloud providers
  • Disaster recovery: Moving to a backup server after an outage
  • Load balancing: Redistributing bots across multiple server instances
  • Environment transitions: Moving from development to production
If the same bot is logged in on multiple servers simultaneously, update delivery is not guaranteed. Always properly deregister from the old server before starting on the new one.

​
Understanding the Data Directory

Each bot stores its data in a subdirectory named after the bot’s user ID within the server’s working directory (default: /data). 
/data/
├── 123456789/          # Bot user ID subdirectory
│   ├── photos/
│   ├── videos/
│   ├── documents/
│   └── ...             # Other bot-specific data
├── 987654321/          # Another bot's subdirectory
└── logs/
    └── telegram-bot-api.log
The bot user ID is different from the bot token. You can find it by calling getMe on your bot or extracting it from the first part of your bot token (before the colon).

​
Migration Procedure

1

Call logOut on the old server

First, deregister your bot from the current server by calling logOut:
curl http://old-server:8081/bot<YOUR_BOT_TOKEN>/logOut
This prevents the old server from receiving any new updates and prepares the bot for migration.
Do not skip this step. Running the same bot on multiple servers will cause unpredictable behavior and update loss.
2

Optional: Clean up webhook and close connection

To minimize update loss during migration, perform these additional cleanup steps:
# Delete webhook configuration
curl http://old-server:8081/bot<YOUR_BOT_TOKEN>/deleteWebhook

# Close the bot connection gracefully
curl http://old-server:8081/bot<YOUR_BOT_TOKEN>/close
Calling deleteWebhook and close helps ensure a clean shutdown and reduces the risk of losing updates during the transition.
3

Stop the old server container

Ensure the old server is fully stopped before moving data:
docker stop telegram-bot-api
This prevents file corruption during the data transfer.
4

Transfer the bot subdirectory

Move the bot’s data directory from the old server to the new server.If servers are on the same host:
# Copy the bot subdirectory
cp -r ./old-data/<BOT_USER_ID> ./new-data/<BOT_USER_ID>
If servers are on different hosts:
# On the old server, create an archive
tar -czf bot-data.tar.gz -C /path/to/old-data <BOT_USER_ID>

# Transfer to new server
scp bot-data.tar.gz user@new-server:/path/to/new-data/

# On the new server, extract
tar -xzf bot-data.tar.gz -C /path/to/new-data/
Using Docker volumes:
# On the old server
docker cp telegram-bot-api:/data/<BOT_USER_ID> ./bot-backup/

# Transfer to new server, then:
docker cp ./bot-backup/<BOT_USER_ID> new-telegram-bot-api:/data/
Ensure the bot subdirectory has the correct ownership and permissions on the new server. The directory should be readable and writable by the user running the Telegram Bot API server (typically botapi with UID 1000).
# Set correct ownership (if needed)
chown -R 1000:1000 /path/to/new-data/<BOT_USER_ID>
5

Start the new server

Launch the Telegram Bot API server on the new host:
docker run -d --name telegram-bot-api \
  --env-file .env \
  -p 8081:8081 -p 8082:8082 \
  -v "$(pwd)/new-data:/data" \
  ragnarok22/telegram-bot-api-docker
The server will automatically detect the existing bot data in the transferred subdirectory.
6

Update bot client configuration

Point your bot application to the new server:
# Update base URL to new server address
app = ApplicationBuilder().token("YOUR_BOT_TOKEN").base_url(
    "http://new-server:8081/bot"
).build()
Restart your bot application after updating the configuration.

​
Verification Steps

After completing the migration, verify everything is working correctly:
1

Check bot identity

curl http://new-server:8081/bot<TOKEN>/getMe
Verify the response contains the correct bot information.
2

Verify webhook configuration

If using webhooks, check and reconfigure if necessary:
# Check current webhook
curl http://new-server:8081/bot<TOKEN>/getWebhookInfo

# Set webhook if needed
curl -X POST http://new-server:8081/bot<TOKEN>/setWebhook \
  -d "url=https://your-domain.com/webhook"
3

Test file access

If your bot stores files, verify they are accessible:
# List bot directory contents (inside container)
docker exec telegram-bot-api ls -la /data/<BOT_USER_ID>/
Send a file to your bot and ensure it’s stored correctly in the new location.
4

Monitor logs

Check the server logs for any errors:
# View container logs
docker logs telegram-bot-api

# View API server logs
docker exec telegram-bot-api tail -f /data/logs/telegram-bot-api.log

​
Preventing Update Loss

To minimize the risk of losing updates during migration:
  1. Schedule during low-activity periods: Migrate when your bot has minimal traffic
  2. Use close method: Call close before logOut to gracefully shut down the connection
  3. Quick transition: Minimize the time between logging out of the old server and starting the new one
  4. Monitor update IDs: Track the last received update ID before and after migration to detect any gaps
  5. Test in development: Practice the migration process with a test bot first
Telegram’s update delivery system is designed to be resilient. Brief disconnections during migration typically don’t result in lost updates, as Telegram will retry delivery to the new server once it’s online.

​
Rollback Procedure

If issues arise after migration, you can roll back to the old server:
1

Log out from new server

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

Restart old server

Start the old server with the original data:
docker start telegram-bot-api
3

Revert bot client

Update your bot application to point back to the old server.

​
Common Issues

  • Permission denied errors: Ensure the bot subdirectory has correct ownership (UID 1000 for the botapi user)
  • Bot data not found: Verify the subdirectory name matches the bot’s user ID exactly
  • Updates not arriving: Confirm you called logOut on the old server and the new server is properly started
  • File paths broken: If using local mode, ensure TELEGRAM_LOCAL is set consistently on the new server

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us