Quickstart

Get your Telegram Bot API server running in 5 minutes

Prerequisites

Before starting, ensure you have:

Docker Installed

Install Docker for your platform

Telegram API Credentials

Get your API ID and Hash from my.telegram.org

Getting API Credentials: Visit my.telegram.org, log in with your phone number, go to “API development tools”, and create an application to receive your api_id and api_hash.

Option 1: Docker Run (Fastest)

This is the quickest way to get started with a single command.

1. Pull the Docker image

   Download the latest image from Docker Hub:

   docker pull ragnarok22/telegram-bot-api-docker
   

   The image is multi-arch and will automatically pull the correct version for your platform (amd64 or arm64).

2. Create environment file

   Create a .env file with your Telegram API credentials:

   .env

   TELEGRAM_API_ID=12345
   TELEGRAM_API_HASH=1234567890abcdef1234567890abcdef
   

   Replace the values with your actual credentials from my.telegram.org.

   You can also add optional configuration like custom ports or enable local mode:

   TELEGRAM_API_ID=12345
   TELEGRAM_API_HASH=1234567890abcdef1234567890abcdef
   TELEGRAM_HTTP_PORT=8081
   TELEGRAM_HTTP_STAT_PORT=8082
   TELEGRAM_LOCAL=true
   TELEGRAM_EXTRA_ARGS=--max-webhook-connections 80
   
3. Start the container

   Run the container with your environment file:

   docker run -d --name telegram-bot-api \
     --env-file .env \
     -p 8081:8081 -p 8082:8082 \
     -v "$(pwd)/data:/data" \
     ragnarok22/telegram-bot-api-docker
   

   What this does:

   • -d: Runs in detached mode (background)
   • --name telegram-bot-api: Names the container for easy reference
   • --env-file .env: Loads your API credentials
   • -p 8081:8081: Exposes the API endpoint on port 8081
   • -p 8082:8082: Exposes the statistics endpoint on port 8082
   • -v "$(pwd)/data:/data": Mounts a local data directory for persistent storage
4. Verify the server is running

   Check the container logs to confirm startup:

   docker logs telegram-bot-api
   

   You should see output like:

   Starting telegram-bot-api (Bot API 9.5) with args: --http-port 8081 --http-stat-port 8082 --dir /data --temp-dir /tmp --log /data/logs/telegram-bot-api.log
   
5. Test with your bot token

   Make a test API call using your bot token:

   curl http://localhost:8081/bot<YOUR_BOT_TOKEN>/getMe
   

   Replace <YOUR_BOT_TOKEN> with your actual bot token. You should receive a JSON response with your bot’s information:

   {
     "ok": true,
     "result": {
       "id": 123456789,
       "is_bot": true,
       "first_name": "MyBot",
       "username": "my_bot"
     }
   }
   

Option 2: Docker Compose (Recommended for Production)

Docker Compose makes it easier to manage configuration and restart the server.

1. Create environment file

   Create a .env file with your credentials:

   .env

   TELEGRAM_API_ID=12345
   TELEGRAM_API_HASH=1234567890abcdef1234567890abcdef
   # Optional overrides:
   # TELEGRAM_HTTP_PORT=8081
   # TELEGRAM_HTTP_STAT_PORT=8082
   # TELEGRAM_DIR=/data
   # TELEGRAM_TEMP_DIR=/tmp
   # TELEGRAM_LOG_FILE=/data/logs/telegram-bot-api.log
   # TELEGRAM_LOCAL=true
   # TELEGRAM_EXTRA_ARGS=--max-webhook-connections 80
   
2. Create docker-compose.yml

   Create a docker-compose.yml file (or use the one from the repository):

   docker-compose.yml

   services:
     telegram-bot-api:
       image: ragnarok22/telegram-bot-api-docker
       env_file: .env
       ports:
         - "8081:8081"
         - "8082:8082"
       volumes:
         - ./data:/data
   

   If you want to build from source instead of using the published image, use the repository’s compose.yml:

   services:
     telegram-api:
       build:
         context: .
         dockerfile: Dockerfile
       restart: unless-stopped
       ports:
         - "8081:8081"
         - "8082:8082"
       env_file: .env
       volumes:
         - ./data:/data
       healthcheck:
         test: ["CMD", "wget", "-qO-", "http://localhost:8081/"]
         interval: 30s
         timeout: 5s
         retries: 3
       deploy:
         resources:
           limits:
             memory: 512M
             cpus: "1.0"
   
3. Start the service

   Launch the server using Docker Compose:

   docker compose up -d
   

   This will:

   • Pull the image (if not already present)
   • Create and start the container
   • Set up networking and volumes
   • Run in the background
4. Verify and test

   Check the logs:

   docker compose logs -f telegram-bot-api
   

   Test the API:

   curl http://localhost:8081/bot<YOUR_BOT_TOKEN>/getMe
   

Advanced Usage Examples

Custom Ports

Run the server on different ports:

docker run -d --env-file .env \
  -e TELEGRAM_HTTP_PORT=9000 \
  -e TELEGRAM_HTTP_STAT_PORT=9001 \
  -p 9000:9000 -p 9001:9001 \
  ragnarok22/telegram-bot-api-docker

Local Mode (Large Files)

Enable local mode for handling files up to 2000 MB:

docker run -d --env-file .env \
  -e TELEGRAM_LOCAL=true \
  -p 8081:8081 -p 8082:8082 \
  -v "$(pwd)/data:/data" \
  ragnarok22/telegram-bot-api-docker

Security Warning: Local mode allows the server to serve local files with absolute paths. Only enable this in trusted environments with proper network isolation.

Extra Arguments

Pass additional flags to the upstream telegram-bot-api binary:

docker run -d --env-file .env \
  -e TELEGRAM_EXTRA_ARGS="--max-webhook-connections 50 --log-verbosity-level 3" \
  -p 8081:8081 -p 8082:8082 \
  ragnarok22/telegram-bot-api-docker

Check Server Version

Run a one-off command to check the version:

docker run --rm ragnarok22/telegram-bot-api-docker ./telegram-bot-api --version

This bypasses the entrypoint script and executes the command directly.

Updating Your Bot Client

Once your server is running, update your bot client to use the local API:

Python (python-telegram-bot)

from telegram.ext import Application

# Point to your local server
app = Application.builder() \
    .token("YOUR_BOT_TOKEN") \
    .base_url("http://localhost:8081/bot") \
    .base_file_url("http://localhost:8081/file/bot") \
    .build()

Important: Before switching from api.telegram.org, call the logOut method to ensure your bot receives all updates. See the Migration Guide for details.

Monitoring and Logs

Access logs to troubleshoot issues:

# View container logs
docker logs telegram-bot-api

# Follow logs in real-time
docker logs -f telegram-bot-api

# Check the log file inside the container
docker exec telegram-bot-api cat /data/logs/telegram-bot-api.log

# Or access from the mounted volume
cat data/logs/telegram-bot-api.log

Check the statistics endpoint:

curl http://localhost:8082/

Troubleshooting

Container fails to start with 'TELEGRAM_API_ID is not set'

Solution: Ensure your .env file contains valid TELEGRAM_API_ID and TELEGRAM_API_HASH values:

cat .env

The file should have:

TELEGRAM_API_ID=12345
TELEGRAM_API_HASH=your_hash_here

Permission denied errors with /data directory

Solution: Create the data directory before starting the container:

mkdir -p data/logs
chmod 755 data

The container runs as user botapi (non-root) and needs write access.

Port already in use error

Solution: Change the ports in your configuration:

# In .env file
TELEGRAM_HTTP_PORT=9000
TELEGRAM_HTTP_STAT_PORT=9001

And update the port mappings:

docker run -d --env-file .env -p 9000:9000 -p 9001:9001 ...

API calls return 'Unauthorized' or fail

Solution:

1. Verify your bot token is correct
2. Check that the server is fully started (view logs)
3. If you just switched from api.telegram.org, call logOut first
4. Check /data/logs/telegram-bot-api.log for detailed errors

Next Steps

Configuration Guide

Learn about all environment variables and advanced options

Migration from api.telegram.org

Safely switch your existing bot to the local server

Docker Compose Setup

Production deployment with health checks and resource limits

Troubleshooting

Common issues and solutions