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.

​
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"
  }
}
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: 
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

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
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.
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 ...
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

Build docs developers (and LLMs) love

Get started for freeTalk to us