Quick Start Guide

This guide will get you from zero to a running Telegram bot with AI responses in under 5 minutes using Docker.

Prerequisites

Before starting, ensure you have:

Docker and Docker Compose installed
A Telegram account to create a bot
An OpenRouter account for AI responses (free tier available)

If you don’t have Docker installed, see the Installation Guide for detailed setup instructions.

Step 1: Clone the Repository

git clone https://github.com/acamus79/TlgrmBot.git
cd TlgrmBot

Step 2: Get Your API Keys

Create a Telegram Bot

Open Telegram and start a chat with @BotFather:

/newbot

Follow the prompts to:

Choose a name for your bot (e.g., “My AI Assistant”)
Choose a username (must end in bot, e.g., my_ai_assistant_bot)
Copy the bot token that BotFather provides

Save this token securely - you’ll need it in the next step. It looks like: 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

Get OpenRouter API Key

Visit OpenRouter.ai
Sign up for a free account
Navigate to Keys section
Click Create Key and copy the generated key

OpenRouter provides free access to several AI models. The default configuration uses tngtech/deepseek-r1t2-chimera:free.

Generate JWT Secret

Generate a secure random string for signing JWT tokens:

openssl rand -base64 32

Copy the output - you’ll use this as your JWT secret.

Step 3: Configure Environment Variables

Create a .env file in the project root:

cp .env.example .env

Edit the .env file with your actual values:

.env

# Database credentials
DB_USER=postgres
DB_PASSWORD=your_secure_password_here

# Telegram bot token from @BotFather
TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

# OpenRouter API key
OPENROUTE_KEY=sk-or-v1-your-key-here

# AI Configuration (optional - defaults provided)
AI_SYSTEM_PROMPT="You are a helpful AI assistant."
AI_TEMPERATURE=1.0
AI_MAX_TOKENS=150

# JWT secret (use output from openssl command)
JWT_SECRET=your_generated_secret_from_openssl

Never commit the .env file to version control! It contains sensitive credentials. The .gitignore file already excludes it.

Configuration Options Explained

Variable	Description	Default	Required
`DB_USER`	PostgreSQL username	`postgres`	Yes
`DB_PASSWORD`	PostgreSQL password	-	Yes
`TELEGRAM_BOT_TOKEN`	Your bot token from @BotFather	-	Yes
`OPENROUTE_KEY`	OpenRouter API key	-	Yes
`AI_SYSTEM_PROMPT`	AI personality/behavior instructions	Chaotic Spanish AI	No
`AI_TEMPERATURE`	Response creativity (0.1-2.0)	`1.2`	No
`AI_MAX_TOKENS`	Maximum response length	`150`	No
`JWT_SECRET`	Secret for signing auth tokens	-	Yes

Step 4: Launch with Docker Compose

Start all services with a single command:

docker-compose up --build

You should see output similar to:

[+] Running 2/2
 ✔ Container telegrm-db   Healthy
 ✔ Container telegrm-api  Started

The first build takes 2-3 minutes as Maven downloads dependencies and compiles the application. Subsequent starts are much faster.

Wait for the application to fully start. You’ll see:

telegrm-api  | Started TelegrmApplication in 8.342 seconds

Step 5: Verify the Application

Check Health Endpoint

curl http://localhost:8080/actuator/health

Expected response:

{"status":"UP"}

Access Swagger UI

Open your browser and navigate to:http://localhost:8080/swagger-ui.htmlYou should see the interactive API documentation with all available endpoints.

Step 6: Create Your First User

curl -X POST http://localhost:8080/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Admin User",
    "email": "[email protected]",
    "password": "SecurePassword123!"
  }'

Step 7: Authenticate and Get Token

curl -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePassword123!"
  }'

Copy this token - you’ll need it to access protected endpoints. The token is valid for 24 hours.

Step 8: Test the Telegram Bot

Find Your Bot on Telegram

Open Telegram and search for the username you chose during bot creation (e.g., @my_ai_assistant_bot)

Start a Conversation

Send a message to your bot:

Hello, bot!

The bot should respond with an AI-generated message within a few seconds.

View Conversation via API

List all conversations using your JWT token:

curl http://localhost:8080/api/conversations \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Response:

[
  {
    "id": "conv-123",
    "participantName": "YourTelegramUsername",
    "lastMessageAt": "2024-03-05T10:30:00Z"
  }
]

Step 9: Send a Proactive Message

Now send a message FROM the API TO Telegram:

curl -X POST http://localhost:8080/api/conversations/conv-123/messages \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "This is a proactive message sent from the API!"
  }'

You should receive this message in your Telegram chat!

Using Swagger UI (Alternative)

You can also test the API through the interactive documentation:

Open Swagger UI

Navigate to http://localhost:8080/swagger-ui.html

Authenticate

Click the Authorize button (top right)
Enter your token in the format: Bearer YOUR_TOKEN_HERE
Click Authorize then Close

Test Endpoints

Now you can click on any endpoint, fill in parameters, and click Execute to test it directly from the browser.

Architecture at Runtime

Here’s what happens when you send a Telegram message:

Stopping the Application

To stop all containers:

# Stop and keep data
docker-compose down

# Stop and remove all data (including database)
docker-compose down -v

Next Steps

View Logs

docker-compose logs -f app

Monitor application logs in real-time

Customize AI Behavior

Edit AI_SYSTEM_PROMPT in .env to change your bot’s personality

Explore API Endpoints

Check out all available endpoints in Swagger UI at /swagger-ui.html

Local Development

Set up the project for local development without Docker

Troubleshooting

Bot doesn't respond to messages

Check application logs: docker-compose logs -f app
Verify TELEGRAM_BOT_TOKEN in .env is correct
Ensure the bot is not already running elsewhere (only one instance can poll)
Check that Telegram user started the bot (sent /start or any message)

Database connection errors

Verify DB_PASSWORD matches in .env
Check database health: docker-compose ps
Wait for database to become healthy (check logs: docker-compose logs db)

AI responses fail

Verify OPENROUTE_KEY is valid
Check OpenRouter account has credits/quota
Review app logs for specific API errors

Port 8080 already in use

Edit docker-compose.yml to change the port mapping:

ports:
  - "9090:8080"  # Use port 9090 instead

For more detailed installation options and local development setup, see the Installation Guide.

Get Started

Architecture

Guides

Deployment

Quick Start

Quick Start Guide

Prerequisites

Step 1: Clone the Repository

Step 2: Get Your API Keys

Step 3: Configure Environment Variables

Configuration Options Explained

Step 4: Launch with Docker Compose

Step 5: Verify the Application

Step 6: Create Your First User

Step 7: Authenticate and Get Token

Step 8: Test the Telegram Bot

Step 9: Send a Proactive Message

Using Swagger UI (Alternative)

Architecture at Runtime

Stopping the Application

Next Steps

View Logs

Customize AI Behavior

Explore API Endpoints

Local Development

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Architecture

Guides

Deployment

​Quick Start Guide

​Prerequisites

​Step 1: Clone the Repository

​Step 2: Get Your API Keys

​Step 3: Configure Environment Variables

​Configuration Options Explained

​Step 4: Launch with Docker Compose

​Step 5: Verify the Application

​Step 6: Create Your First User

​Step 7: Authenticate and Get Token

​Step 8: Test the Telegram Bot

​Step 9: Send a Proactive Message

​Using Swagger UI (Alternative)

​Architecture at Runtime

​Stopping the Application

​Next Steps

View Logs

Customize AI Behavior

Explore API Endpoints

Local Development

​Troubleshooting

Build docs developers (and LLMs) love

Quick Start Guide

Prerequisites

Step 1: Clone the Repository

Step 2: Get Your API Keys

Step 3: Configure Environment Variables

Configuration Options Explained

Step 4: Launch with Docker Compose

Step 5: Verify the Application

Step 6: Create Your First User

Step 7: Authenticate and Get Token

Step 8: Test the Telegram Bot

Step 9: Send a Proactive Message

Using Swagger UI (Alternative)

Architecture at Runtime

Stopping the Application

Next Steps

Troubleshooting