Telegram Bot API Dockerized

Dockerized Telegram Bot API server.

The Telegram Bot API provides an HTTP API for creating Telegram Bots.

Table of Contents

• Installation
• Usage
• Documentation
• Moving a bot to a local server
• Moving a bot from one local server to another
• License

Installation

• Install Docker
• Pull the image from Docker Hub (multi-arch: amd64/arm64)

  docker pull ragnarok22/telegram-bot-api-docker

• Create a .env file with the following content

  TELEGRAM_API_ID=12345
  TELEGRAM_API_HASH=1234567890abcdef1234567890abcdef

  You can get the TELEGRAM_API_ID and TELEGRAM_API_HASH from Telegram's website
• Run the container

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

• (Optional) Mount volumes to persist data and logs between runs

  docker run -d --env-file .env -p 8081:8081 \
    -v $(pwd)/data:/data \
    -v $(pwd)/logs:/data/logs \
    ragnarok22/telegram-bot-api-docker

• The server will be available at http://localhost:8081

Also, you can use Docker Compose to run the container

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

Apple Silicon (M1/M2/M3) and ARM64

The image supports multi-platform builds for both linux/amd64 and linux/arm64.

For pre-built images: Docker will automatically pull the correct variant for your host architecture.

For local builds on ARM64 (Apple Silicon): The Dockerfile now supports native ARM64 builds. Simply run:

docker build -t telegram-bot-api .

Running on Apple Silicon: If you still see platform warnings, force the platform explicitly:

docker run -d --platform linux/arm64 --env-file .env -p 8081:8081 ragnarok22/telegram-bot-api-docker

Building from Source

To build the image locally:

docker build -t telegram-bot-api .

The Dockerfile automatically creates the necessary log directories and handles platform-specific builds.

Environment Variables

• TELEGRAM_API_ID: The API ID obtained from Telegram's website
• TELEGRAM_API_HASH: The API hash obtained from Telegram's website
• TELEGRAM_HTTP_PORT: The port the server will listen to. Default is 8081
• TELEGRAM_HTTP_STAT_PORT: The port the server will listen to for statistics. Default is 8082
• TELEGRAM_DIR: The directory where the server will store the data. Default is /data
• TELEGRAM_TEMP_DIR: The directory where the server will store temporary files. Default is /tmp
• TELEGRAM_LOG_FILE: The file where the server will store the logs. Default is /data/logs/telegram-bot-api.log
• TELEGRAM_LOCAL: Set to 1 or true (case-insensitive) to run the server in local mode. Default is false

Usage

Run the container by providing the required environment variables. If you created a .env file in the installation step, it can be passed directly to Docker:

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

After starting the container the API is available on the port configured via TELEGRAM_HTTP_PORT. You can verify your setup with:

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

You may also launch the service using Docker Compose:

docker compose up -d

The compose configuration keeps bot data in the ./data directory. Temporary files are stored in the ./temp directory.

Documentation

See Bots: An introduction for developers for a brief description of Telegram Bots and their features.

See the Telegram Bot API documentation for a description of the Bot API interface and a complete list of available classes, methods and updates.

See the Telegram Bot API server build instructions generator for detailed instructions on how to build the Telegram Bot API server.

Subscribe to @BotNews to be the first to know about the latest updates and join the discussion in @BotTalk.

Switching

To guarantee that your bot will receive all updates, you must deregister it with the https://api.telegram.org server by calling the method logOut. After the bot is logged out, you can replace the address to which the bot sends requests with the address of your local server and use it in the usual way. If the server is launched in --local mode, make sure that the bot can correctly handle absolute file paths in response to getFile requests.

Moving

If the bot is logged in on more than one server simultaneously, there is no guarantee that it will receive all updates. To move a bot from one local server to another you can use the method logOut to log out on the old server before switching to the new one.

If you want to avoid losing updates between logging out on the old server and launching on the new server, you can remove the bot's webhook using the method deleteWebhook, then use the method close to close the bot instance. After the instance is closed, locate the bot's subdirectory in the working directory of the old server by the bot's user ID, move the subdirectory to the working directory of the new server and continue sending requests to the new server as usual.

License

Telegram Bot API server source code is licensed under the terms of the Boost Software License. See LICENSE for more information.