QR Code Generator Telegram Bot

This project is a Telegram bot that generates QR codes for URLs, WIFI auto-connection, visit card (vcard) and more sent by users. The bot validates the data and returns a QR code image.

Bot deployment is currently on Northflank, you can pay a visit directly in Telegram accessing the qrcodegen-bot.

Features

• Data validation using Pydantic.
• QR code generation using the qrcode library.
• Asynchronous handling of Telegram messages, thanks python-telegram-bot people.
• Future features: different kind of QR codes with inlinekeyboard guidance.

Getting Started

Prerequisites

• Docker
• Docker Compose

Installation

📦 Pull the Image from Docker Hub

1. Pull the image from Docker Hub: To get the latest version of qrcodegen, pull it from Docker Hub:

   docker pull jpizquierdo/qrcodegen:latest

2. Run the container:

   docker run --env TELEGRAM_TOKEN=yourGodFatherFancyToken -d jpizquierdo/qrcodegen:latest

3. Or run the container with docker compose:

   Create a .env file with your Telegram bot token (check .env.example):

   TELEGRAM_TOKEN="your_telegram_bot_token"

   Execute:

   docker compose up -d

Build the image yourself

1. Clone the repository:

   git clone https://github.com/jpizquierdo/qrcodegen.git
   cd qrcodegen

2. Create a .env file with your Telegram bot token (check .env.example):

   TELEGRAM_TOKEN="your_telegram_bot_token"

3. Build and run the Docker containers:

   docker compose up -d --build

4. Open Telegram and send a message to your bot clicking in any button like a URL. The bot will respond with a QR code image.

Usage - docker run

If you prefer to use docker run sentence and build the image yourself follow the these steps:

1. Build the image from Dockerfile:

   docker build -t qrcode_generator_bot .

2. Run the container with the environment variable:

   docker run --env TELEGRAM_TOKEN=your_secret_token -d qrcode_generator_bot

3. Open Telegram and send a message to your bot clicking in any button like a URL. The bot will respond with a QR code image.

Observability (Optional)

This project includes optional observability features powered by OpenTelemetry. Traces and logs are exported via OTLP HTTP and work with any compatible backend (Grafana Cloud, Jaeger, Honeycomb, a local OpenTelemetry Collector, etc.).

How to Enable Observability

Set the following variables in your .env file:

OTEL_ENABLED=true
OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
# Optional: auth headers as comma-separated key=value pairs
# OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic <token>"

OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_HEADERS are standard OpenTelemetry environment variables read directly by the SDK.

Example: Grafana Cloud

1. Go to your Grafana Cloud stack → OpenTelemetry to get your OTLP endpoint.
2. Create an API key with MetricsPublisher and LogsPublisher roles.
3. Base64-encode your credentials: echo -n "INSTANCE_ID:API_KEY" | base64
4. Set the variables:

OTEL_ENABLED=true
OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp-gateway-prod-<region>.grafana.net/otlp"
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic <base64(INSTANCE_ID:API_KEY)>"

Note: Observability is disabled by default (OTEL_ENABLED=false). When disabled, a no-op tracer is used automatically with no performance overhead.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

This project is licensed under the MIT License.