Configuration

Configure the Telegram Bot API server with environment variables

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

TELEGRAM_API_ID=12345

Variable	Type	Description
TELEGRAM_API_ID	Integer	API ID from my.telegram.org
TELEGRAM_API_HASH	String	API 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

Variable	Default	Description
TELEGRAM_HTTP_PORT	8081	Port for the HTTP API endpoint
TELEGRAM_HTTP_STAT_PORT	8082	Port for the statistics endpoint

Default Ports

TELEGRAM_HTTP_PORT=8081
TELEGRAM_HTTP_STAT_PORT=8082

Storage Configuration

Variable	Default	Description
TELEGRAM_DIR	/data	Directory for bot data and sessions
TELEGRAM_TEMP_DIR	/tmp	Temporary directory for HTTP file uploads
TELEGRAM_LOG_FILE	/data/logs/telegram-bot-api.log	Path to the log file

Default Storage

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

Variable	Default	Description
TELEGRAM_LOCAL	disabled	Enable 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

Variable	Default	Description
TELEGRAM_EXTRA_ARGS	empty	Additional 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:

Webhook Limits

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

Using .env File (Recommended)

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