Skip to main content

​
Environment Configuration

The TelegramBot API uses environment variables for configuration. This guide covers all required and optional variables.

​
Getting Started

1

Create environment file

Copy the .env.example file to .env in the project root:
cp .env.example .env
2

Configure required variables

Open the .env file and fill in the required values as described below.
3

Verify configuration

Ensure all required variables are set before starting the application.

​
Required Variables

These variables must be configured for the application to work properly.

​
Database Configuration

Type: String
Default: postgres
Description: PostgreSQL database username.
DB_USER=postgres
The default value postgres typically works with standard PostgreSQL installations.
Type: String
Required: Yes
Description: Password for the PostgreSQL database user.
DB_PASSWORD=secret_password
Use a strong, unique password in production environments.
Type: JDBC URL
Required: Only for local development without Docker
Description: Full JDBC connection URL for PostgreSQL.
DB_URL=jdbc:postgresql://localhost:5432/telegrmdb
This variable is only needed when running locally without Docker. Docker Compose automatically sets this.

​
Telegram Configuration

Type: String
Required: Yes
Description: Authentication token for your Telegram bot.
TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
How to obtain:
  1. Open Telegram and search for @BotFather
  2. Send /newbot command
  3. Follow the prompts to create your bot
  4. Copy the token provided by BotFather
See the Telegram Setup Guide for detailed instructions.
Keep this token secret! Anyone with this token can control your bot.

​
AI Configuration (OpenRouter)

Type: String
Required: Yes
Description: API key for accessing AI models through OpenRouter.
OPENROUTE_KEY=sk-or-v1-abc123def456...
How to obtain:
  1. Visit OpenRouter.ai
  2. Create an account or sign in
  3. Navigate to the “Keys” section
  4. Generate a new API key
  5. Copy the key to your .env file
See the AI Configuration Guide for more details.
This key provides access to paid AI services. Keep it secure and monitor usage.

​
Security Configuration

Type: String
Required: Yes
Description: Secret key used to sign and verify JWT authentication tokens.
JWT_SECRET=un_secreto_muy_largo_y_seguro_para_firmar_tokens
How to generate:
openssl rand -base64 32
Use a strong, random value. Never commit this to version control!
The JWT token expires after 24 hours by default (configurable in application.yaml).

​
Optional Variables

These variables have default values but can be customized for your use case.

​
AI Behavior Configuration

Type: String
Default: "IA caótica en español sin lógica, patos espaciales, humor cambiante (no agresivo), sin ser útil."
Description: System prompt that defines the AI bot’s personality and behavior.
AI_SYSTEM_PROMPT="Eres una IA demente..."
Customize this to create different bot personalities. The prompt greatly influences response style.
Type: Float (0.0 - 2.0)
Default: 1.2
Description: Controls AI response creativity and randomness.
AI_TEMPERATURE=1.4
Guidelines:
  • 0.1 - 0.5: Very predictable and conservative
  • 0.6 - 1.0: Balanced responses
  • 1.1 - 1.5: Creative and varied
  • 1.6 - 2.0: Highly random and chaotic
Higher values produce more creative but less predictable responses.
Type: Integer
Default: 150
Description: Maximum length of AI-generated responses.
AI_MAX_TOKENS=200
Higher values allow longer responses but consume more API credits.

​
Configuration File Reference

​
Complete .env.example

# --- Variables Requeridas ---

# Base de Datos
DB_USER=postgres
DB_PASSWORD=secret_password

# Telegram
TELEGRAM_BOT_TOKEN=tu_token_de_telegram_aqui

# IA (OpenRouter)
OPENROUTE_KEY=tu_clave_de_openrouter_aqui
AI_SYSTEM_PROMPT="Eres una IA demente..."
AI_TEMPERATURE=1.4
AI_MAX_TOKENS=200

# Seguridad
JWT_SECRET=un_secreto_muy_largo_y_seguro_para_firmar_tokens

# --- Opcional para Desarrollo Local (sin Docker) se necesita una DB Postgresql ---
# DB_URL=jdbc:postgresql://localhost:5432/telegrmdb

​
Application Properties Mapping

The environment variables map to Spring Boot application properties as follows:
Environment VariableApplication PropertyLocation
DB_USERspring.datasource.usernameapplication.yaml:8
DB_PASSWORDspring.datasource.passwordapplication.yaml:9
DB_URLspring.datasource.urlapplication.yaml:7
TELEGRAM_BOT_TOKENtelegram.bot-tokenapplication.yaml:24
OPENROUTE_KEYopenrouter.api-keyapplication.yaml:27
AI_SYSTEM_PROMPTopenrouter.system-promptapplication.yaml:30
AI_TEMPERATUREopenrouter.temperatureapplication.yaml:31
AI_MAX_TOKENSopenrouter.max-tokensapplication.yaml:32
JWT_SECRETjwt.secretapplication.yaml:35

​
Validation and Troubleshooting

Common Issues:
  1. Missing required variables: The application will fail to start with a clear error message.
  2. Invalid JWT_SECRET: Authentication will fail if the secret is too short or weak.
  3. Invalid TELEGRAM_BOT_TOKEN: Bot polling will fail with 401 Unauthorized.
  4. Invalid OPENROUTE_KEY: AI responses will return error messages.

​
Verifying Configuration

You can verify your configuration is loaded correctly by checking the application startup logs: 
docker-compose up
Look for successful initialization messages for:
  • Database connection
  • Flyway migrations
  • Telegram bot polling
  • OpenRouter AI adapter
Use docker-compose logs -f to follow logs in real-time and catch configuration errors early.

​
Security Best Practices

1

Never commit .env file

Ensure .env is in your .gitignore file.
2

Use different secrets per environment

Development, staging, and production should have unique JWT_SECRET values.
3

Rotate secrets regularly

Change JWT_SECRET and OPENROUTE_KEY periodically, especially after team changes.
4

Use environment-specific .env files

Consider using .env.dev, .env.staging, .env.prod for different environments.

​
Next Steps

Telegram Setup

Learn how to create and configure your Telegram bot

AI Configuration

Configure AI behavior and model selection

Development Guide

Set up your local development environment

Authentication

Understand the JWT authentication flow

Build docs developers (and LLMs) love

Get started for freeTalk to us