Environment Variables

Configure the Telegram Bot API server using environment variables

The Telegram Bot API Docker container is configured entirely through environment variables. The entrypoint script parses these variables and passes the appropriate flags to the underlying telegram-bot-api binary.

Required Variables

These variables must be set for the container to start:

TELEGRAM_API_ID · string · required

Your Telegram API ID obtained from my.telegram.org.

The container will exit with an error if this is not set.

TELEGRAM_API_ID=12345

TELEGRAM_API_HASH · string · required

Your Telegram API hash obtained from my.telegram.org.

The container will exit with an error if this is not set.

TELEGRAM_API_HASH=1234567890abcdef1234567890abcdef

Optional Variables

These variables have sensible defaults and can be overridden as needed:

TELEGRAM_HTTP_PORT · integer · default: "8081"

The HTTP port where the Bot API server listens for incoming requests.

Corresponds to the --http-port flag.

TELEGRAM_HTTP_PORT=9000

Remember to update your Docker port mapping when changing this value:

docker run -e TELEGRAM_HTTP_PORT=9000 -p 9000:9000 ...

TELEGRAM_HTTP_STAT_PORT · integer · default: "8082"

The HTTP port for the statistics endpoint.

Corresponds to the --http-stat-port flag.

TELEGRAM_HTTP_STAT_PORT=9001

TELEGRAM_DIR · string · default: "/data"

The server working directory where bot data is stored.

Corresponds to the --dir flag.

TELEGRAM_DIR=/data

Each bot’s data is stored in a subdirectory named by its user ID within this directory.

TELEGRAM_TEMP_DIR · string · default: "/tmp"

Directory for storing HTTP server temporary files.

Corresponds to the --temp-dir flag.

TELEGRAM_TEMP_DIR=/tmp

TELEGRAM_LOG_FILE · string · default: "/data/logs/telegram-bot-api.log"

Path to the log file where the server writes its logs.

Corresponds to the --log flag.

TELEGRAM_LOG_FILE=/data/logs/telegram-bot-api.log

Ensure the parent directory exists and is writable by the botapi user (UID/GID typically 100).

TELEGRAM_LOCAL · boolean · default: "false"

Enable local mode to allow the Bot API server to serve local requests and return absolute file paths.

Corresponds to the --local flag.

Accepts 1 or true (case-insensitive) to enable:

TELEGRAM_LOCAL=true
# or
TELEGRAM_LOCAL=1

Local mode should only be enabled in trusted environments with proper network isolation, as it allows serving local files.

TELEGRAM_EXTRA_ARGS · string · default: ""

Additional command-line arguments passed directly to the telegram-bot-api binary.

Use this for advanced configuration options not covered by the dedicated environment variables.

TELEGRAM_EXTRA_ARGS="--max-webhook-connections 50 --log-verbosity-level 3"

Common options include:

• --max-webhook-connections: Maximum number of webhook connections
• --log-verbosity-level: Control log verbosity (0-1023)
• --max-connections: Maximum number of simultaneous connections

See the upstream documentation for all available flags.

Complete Example

Here’s a complete .env file with all variables:

# Required
TELEGRAM_API_ID=12345
TELEGRAM_API_HASH=1234567890abcdef1234567890abcdef

# Optional - custom ports
TELEGRAM_HTTP_PORT=9000
TELEGRAM_HTTP_STAT_PORT=9001

# Optional - paths
TELEGRAM_DIR=/data
TELEGRAM_TEMP_DIR=/tmp
TELEGRAM_LOG_FILE=/data/logs/telegram-bot-api.log

# Optional - local mode
TELEGRAM_LOCAL=true

# Optional - extra arguments
TELEGRAM_EXTRA_ARGS="--max-webhook-connections 80 --log-verbosity-level 2"

How It Works

The entrypoint.sh script (source at entrypoint.sh:9-70) validates required variables, applies defaults for optional ones, and constructs the command-line arguments:

1. Checks that TELEGRAM_API_ID and TELEGRAM_API_HASH are set
2. Builds the argument string with defaults for unset variables
3. Processes the TELEGRAM_LOCAL flag (accepts 1 or true)
4. Appends TELEGRAM_EXTRA_ARGS verbatim to the end
5. Executes telegram-bot-api with the constructed arguments

Validation Errors

If required variables are missing, the container will exit immediately with a clear error:

Error: TELEGRAM_API_ID is not set

or

Error: TELEGRAM_API_HASH is not set

Check your .env file or Docker run command to ensure these are properly set.