Ports

Network ports exposed by the Telegram Bot API server

The Telegram Bot API server exposes two HTTP ports for different purposes. Both ports are configured in the Dockerfile (source at Dockerfile:47) and can be customized via environment variables.

Default Ports

Port 8081 - HTTP API

The main HTTP API endpoint where your bot sends requests.

Default: 8081

Usage:

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

This is the primary port you’ll use for all Bot API methods:

• getMe
• sendMessage
• sendPhoto
• All other Bot API methods

Port 8082 - HTTP Statistics

The statistics endpoint for monitoring server performance and metrics.

Default: 8082

Usage:

curl http://localhost:8082/

This endpoint provides runtime statistics about the server’s operation.

Exposing Ports

Standard Configuration

Map both default ports when running the container:

docker run -d \
  --env-file .env \
  -p 8081:8081 \
  -p 8082:8082 \
  ragnarok22/telegram-bot-api-docker

Using Docker Compose

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

Customizing Ports

You can change the internal ports using environment variables. When you do this, remember to update your Docker port mappings to match.

Custom API Port

Change the HTTP API port to 9000:

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

Custom Statistics Port

Change the statistics port to 9001:

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

Both Custom Ports

Change both ports simultaneously:

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

With Docker Compose:

services:
  telegram-bot-api:
    image: ragnarok22/telegram-bot-api-docker
    env_file: .env
    environment:
      - TELEGRAM_HTTP_PORT=9000
      - TELEGRAM_HTTP_STAT_PORT=9001
    ports:
      - "9000:9000"
      - "9001:9001"
    volumes:
      - ./data:/data

Host Port Mapping

You can map the internal ports to different host ports without changing the internal configuration:

docker run -d \
  --env-file .env \
  -p 8080:8081 \
  -p 8090:8082 \
  ragnarok22/telegram-bot-api-docker

In this example:

• Internal port 8081 is accessible on host port 8080
• Internal port 8082 is accessible on host port 8090

Access the API:

curl http://localhost:8080/bot<TOKEN>/getMe

Port Conflicts

If you see an error like:

Error starting userland proxy: listen tcp4 0.0.0.0:8081: bind: address already in use

Another service is using that port on your host. You have two options:

Option 1: Change Host Mapping

Map to a different host port without changing the container:

docker run -d \
  --env-file .env \
  -p 8091:8081 \
  -p 8092:8082 \
  ragnarok22/telegram-bot-api-docker

Option 2: Change Internal Port

Change the internal port with environment variables:

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

Firewall and Security

By default, Docker exposes mapped ports on all network interfaces (0.0.0.0). If your server is accessible from the internet, these ports will be publicly exposed.

To restrict access to localhost only:

docker run -d \
  --env-file .env \
  -p 127.0.0.1:8081:8081 \
  -p 127.0.0.1:8082:8082 \
  ragnarok22/telegram-bot-api-docker

With Docker Compose:

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

Health Check

The container includes a health check (source at Dockerfile:49-50) that polls the HTTP API port:

HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD wget -qO- http://localhost:8081/ || exit 1

Check container health:

docker ps

Look for the STATUS column - it should show healthy after the server starts.

If you change TELEGRAM_HTTP_PORT, the health check will fail because it still checks port 8081. This is a known limitation. The server will still work, but the health status will be incorrect.

Verifying Port Configuration

After starting the container, verify the ports are working:

# Check API port
curl http://localhost:8081/

# Check statistics port
curl http://localhost:8082/

View the startup logs to see which ports the server is using:

docker logs telegram-bot-api

You should see output like:

Starting telegram-bot-api (Telegram Bot API server 9.5) with args: --http-port 8081 --http-stat-port 8082 ...