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.

​
Configuration Overview

The Telegram Bot API server is configured entirely through environment variables. This approach allows for flexible deployment across different environments without modifying code or configuration files.

​
Getting API Credentials

Before running the server, you need to obtain API credentials from Telegram:
1

Visit my.telegram.org

Navigate to my.telegram.org and log in with your Telegram account.
2

Go to API development tools

Click on “API development tools” in the menu.
3

Create a new application

If you haven’t already, create a new application by filling out the form:
  • App title: Choose any name (e.g., “Bot API Server”)
  • Short name: A shorter identifier
  • Platform: You can select “Other”
  • Description: Optional description of your application
4

Copy your credentials

After creating the application, you’ll receive:
  • API ID: A numeric identifier (e.g., 12345)
  • API Hash: A hexadecimal string (e.g., 1234567890abcdef1234567890abcdef)
Keep these credentials secure - you’ll need them to configure the server.
Never commit your API credentials to version control or share them publicly. These credentials grant access to Telegram’s API on behalf of your account.

​
Creating the .env File

The recommended way to configure the server is using a .env file:
1

Create the file

In your working directory, create a file named .env:
touch .env
2

Add required credentials

Open the file and add your API credentials:
.env
TELEGRAM_API_ID=12345
TELEGRAM_API_HASH=1234567890abcdef1234567890abcdef
3

Add optional configuration (if needed)

Customize other settings as needed:
.env
TELEGRAM_API_ID=12345
TELEGRAM_API_HASH=1234567890abcdef1234567890abcdef
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
4

Secure the file

Restrict file permissions to protect your credentials:
chmod 600 .env

​
Example .env File

The repository includes a .env.example file you can use as a template:
.env.example
TELEGRAM_API_ID=your_api_id_here
TELEGRAM_API_HASH=your_api_hash_here
# 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=
Copy and customize it: 
cp .env.example .env

​
Environment Variables Reference

​
Required Variables

These variables must be set for the server to function: 
TELEGRAM_API_ID=12345
VariableTypeDescription
TELEGRAM_API_IDIntegerAPI ID from my.telegram.org
TELEGRAM_API_HASHStringAPI hash from my.telegram.org
The server will fail to start if these required variables are not provided.

​
Optional Variables

These variables have sensible defaults but can be customized:

​
Network Configuration

VariableDefaultDescription
TELEGRAM_HTTP_PORT8081Port for the HTTP API endpoint
TELEGRAM_HTTP_STAT_PORT8082Port for the statistics endpoint
TELEGRAM_HTTP_PORT=8081
TELEGRAM_HTTP_STAT_PORT=8082

​
Storage Configuration

VariableDefaultDescription
TELEGRAM_DIR/dataDirectory for bot data and sessions
TELEGRAM_TEMP_DIR/tmpTemporary directory for HTTP file uploads
TELEGRAM_LOG_FILE/data/logs/telegram-bot-api.logPath to the log file
TELEGRAM_DIR=/data
TELEGRAM_TEMP_DIR=/tmp
TELEGRAM_LOG_FILE=/data/logs/telegram-bot-api.log
When changing TELEGRAM_DIR or TELEGRAM_LOG_FILE, ensure your volume mounts match the new paths.

​
Feature Flags

VariableDefaultDescription
TELEGRAM_LOCALdisabledEnable local file serving mode
TELEGRAM_LOCAL=true
When enabled, the server runs with the --local flag, allowing it to:
  • Return absolute file paths in getFile responses
  • Serve files directly from the local filesystem
Only enable TELEGRAM_LOCAL in trusted environments with proper network isolation. Local mode can expose sensitive files if not properly secured.

​
Advanced Configuration

VariableDefaultDescription
TELEGRAM_EXTRA_ARGSemptyAdditional flags passed to the telegram-bot-api binary
TELEGRAM_EXTRA_ARGS=--max-webhook-connections 80 --log-verbosity-level 3
Use this to pass any upstream flags not covered by other environment variables. Common examples: 
TELEGRAM_EXTRA_ARGS=--max-webhook-connections 50

​
Configuration Examples

​
Minimal Configuration

For basic usage with all defaults:
.env
TELEGRAM_API_ID=12345
TELEGRAM_API_HASH=1234567890abcdef1234567890abcdef

​
Development Configuration

For local development with verbose logging:
.env
TELEGRAM_API_ID=12345
TELEGRAM_API_HASH=1234567890abcdef1234567890abcdef
TELEGRAM_LOCAL=true
TELEGRAM_EXTRA_ARGS=--log-verbosity-level 3

​
Production Configuration

For production deployment with custom ports and resource limits:
.env
TELEGRAM_API_ID=12345
TELEGRAM_API_HASH=1234567890abcdef1234567890abcdef
TELEGRAM_HTTP_PORT=8081
TELEGRAM_HTTP_STAT_PORT=8082
TELEGRAM_DIR=/data
TELEGRAM_LOG_FILE=/data/logs/telegram-bot-api.log
TELEGRAM_EXTRA_ARGS=--max-webhook-connections 100 --max-connections 50000

​
High-Volume Configuration

For handling many concurrent webhooks:
.env
TELEGRAM_API_ID=12345
TELEGRAM_API_HASH=1234567890abcdef1234567890abcdef
TELEGRAM_EXTRA_ARGS=--max-webhook-connections 200 --max-connections 100000

​
Configuration Methods

With Docker: 
docker run -d --env-file .env \
  -p 8081:8081 -p 8082:8082 \
  ragnarok22/telegram-bot-api-docker
With Docker Compose:
compose.yml
services:
  telegram-bot-api:
    image: ragnarok22/telegram-bot-api-docker
    env_file: .env

​
Using Inline Environment Variables

With Docker: 
docker run -d \
  -e TELEGRAM_API_ID=12345 \
  -e TELEGRAM_API_HASH=1234567890abcdef1234567890abcdef \
  -p 8081:8081 -p 8082:8082 \
  ragnarok22/telegram-bot-api-docker
With Docker Compose:
compose.yml
services:
  telegram-bot-api:
    image: ragnarok22/telegram-bot-api-docker
    environment:
      - TELEGRAM_API_ID=12345
      - TELEGRAM_API_HASH=1234567890abcdef1234567890abcdef

​
Using Docker Secrets (Production)

For production deployments, use Docker secrets: 
echo "12345" | docker secret create telegram_api_id -
echo "1234567890abcdef1234567890abcdef" | docker secret create telegram_api_hash -
compose.yml
services:
  telegram-bot-api:
    image: ragnarok22/telegram-bot-api-docker
    secrets:
      - telegram_api_id
      - telegram_api_hash
    environment:
      - TELEGRAM_API_ID_FILE=/run/secrets/telegram_api_id
      - TELEGRAM_API_HASH_FILE=/run/secrets/telegram_api_hash

secrets:
  telegram_api_id:
    external: true
  telegram_api_hash:
    external: true
Docker secrets provide secure credential management in production environments, especially when using Docker Swarm.

​
Validating Configuration

After configuring the server, verify it’s working correctly:

​
Check Container Logs

docker logs telegram-bot-api
Look for successful startup messages and no error lines.

​
Test the API Endpoint

curl http://localhost:8081/bot<YOUR_BOT_TOKEN>/getMe
You should receive a JSON response with your bot’s information.

​
Check Statistics Endpoint

curl http://localhost:8082/
This returns server statistics and health information.

​
View Log File

docker exec telegram-bot-api cat /data/logs/telegram-bot-api.log
Inspect the log file for detailed startup and runtime information.

​
Configuration Best Practices

Security

  • Never commit .env files to version control
  • Use .gitignore to exclude .env from git
  • Restrict file permissions: chmod 600 .env
  • Use Docker secrets in production
  • Rotate credentials periodically

Performance

  • Increase --max-webhook-connections for high-traffic bots
  • Monitor resource usage with docker stats
  • Adjust memory limits in Docker Compose based on load
  • Use persistent volumes for data directory

Logging

  • Mount the data directory to persist logs
  • Use log rotation for long-running deployments
  • Increase verbosity level for debugging: --log-verbosity-level 3
  • Monitor log file size and disk space

Reliability

  • Use restart: unless-stopped in Docker Compose
  • Configure health checks to monitor service status
  • Set appropriate resource limits to prevent OOM
  • Back up the data directory regularly

​
Troubleshooting Configuration Issues

​
Missing Required Variables

If you see errors about missing API credentials:
  1. Verify .env file exists: ls -la .env
  2. Check file contents: cat .env
  3. Ensure variables are not commented out
  4. Verify --env-file path is correct

​
Port Conflicts

If ports are already in use:
.env
TELEGRAM_HTTP_PORT=9081
TELEGRAM_HTTP_STAT_PORT=9082
Update your Docker run command or Compose file to match: 
docker run -p 9081:9081 -p 9082:9082 ...

​
Permission Denied Errors

If you encounter permission issues with volumes: 
mkdir -p ./data/logs
chmod -R 755 ./data
The container runs as user botapi (non-root) and needs write access.

​
Invalid Credentials

If the server fails to authenticate:
  1. Verify credentials at my.telegram.org
  2. Ensure no extra spaces or quotes in .env
  3. Check that TELEGRAM_API_ID is numeric
  4. Verify TELEGRAM_API_HASH is exactly 32 hexadecimal characters

​
Next Steps

Docker Setup

Learn how to run the server with Docker

Docker Compose

Deploy using Docker Compose

Build docs developers (and LLMs) love

Get started for freeTalk to us