Telegram Bot Setup

This guide walks you through creating a Telegram bot using BotFather and integrating it with the TelegramBot API.

Overview

Telegram bots are special accounts that don’t require a phone number. They’re controlled programmatically via the Telegram Bot API. BotFather is Telegram’s official bot for creating and managing other bots.

The TelegramBot API uses polling to receive messages. The bot continuously checks for new messages from Telegram servers, implemented in TelegramPollingService.java.

Creating Your Bot

Open Telegram

Launch the Telegram app on your device (mobile, desktop, or web).

Find BotFather

Search for @BotFather in the Telegram search bar and start a chat.

BotFather has a blue verification checkmark. Make sure you’re talking to the official bot!

Create a new bot

Send the /newbot command to BotFather.

/newbot

BotFather will respond and ask for a name for your bot.

Choose a name

Send your desired bot name. This is the display name users will see.

My Awesome Bot

This name can contain spaces and special characters.

Choose a username

BotFather will ask for a username. This must:

End with bot (e.g., myawesome_bot or MyAwesomeBot)
Be unique across all Telegram bots
Contain only letters, numbers, and underscores

myawesome_bot

Get your token

If the username is available, BotFather will create your bot and provide an API token:

Done! Congratulations on your new bot. You will find it at t.me/myawesome_bot.

Use this token to access the HTTP API:
1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

Keep your token secure and store it safely, it can be used by anyone to control your bot.

CRITICAL: Keep this token secret! Anyone with access to this token can control your bot.

Configuring Your Bot

Adding the Token to Your Application

Add your bot token to the .env file:

.env

TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

Optional: Customize Bot Settings

You can configure additional bot settings through BotFather:

Set Bot Description

The description appears when users first interact with your bot.

/setdescription

Select your bot and send the description text.

Set About Text

Short text shown in the bot’s profile.

/setabouttext

Set Bot Picture

Upload a profile picture for your bot.

/setuserpic

Select your bot and upload an image.

Set Commands

Define a list of commands that appear in the bot’s menu.

/setcommands

Example command list:

start - Start interacting with the bot
help - Show help information
settings - Configure bot settings

Testing Your Bot

Start the application

With your token configured in .env, start the application:

docker-compose up --build

Find your bot on Telegram

Search for your bot’s username (e.g., @myawesome_bot) in Telegram and start a chat.

Send a message

Send any message to your bot. You should receive an AI-generated response.

The first response might take a few seconds as the AI processes your message.

Check the logs

Monitor your application logs to see message processing:

docker-compose logs -f

You should see log entries for:

Received update from Telegram
Processing message
AI response generation
Reply sent to Telegram

How Telegram Integration Works

Polling Architecture

The application uses a polling mechanism to receive messages:

src/main/java/com/acamus/telegrm/infrastructure/adapters/in/scheduler/TelegramPollingService.java

@Scheduled(fixedDelay = 1000) // Polls every 1 second
public void pollUpdates() {
    // Fetch new updates from Telegram
    // Process each update through the use case
}

Polling vs Webhooks: This implementation uses polling (regularly checking for updates) rather than webhooks (Telegram pushing updates). Polling is simpler to set up and doesn’t require a public HTTPS endpoint.

Message Flow

User sends message

A user sends a message to your bot on Telegram.

Polling service fetches update

TelegramPollingService receives the update via the Telegram Bot API.

Update processing

The update is passed to ProcessTelegramUpdateUseCase which:

Extracts message content and chat information
Finds or creates a conversation record
Saves the user’s message

AI generation

The AI adapter generates a response using OpenRouter.

Reply sent

The bot sends the AI-generated response back to the user via Telegram.

Telegram Configuration in Code

The bot token is configured in the application through:

application.yaml

application.yaml:23-24

telegram:
  bot-token: ${TELEGRAM_BOT_TOKEN}

TelegramConfig

src/main/java/com/acamus/telegrm/infrastructure/config/TelegramConfig.java

@Configuration
public class TelegramConfig {
    @Value("${telegram.bot-token}")
    private String botToken;
    
    @Bean
    public RestClient telegramRestClient() {
        return RestClient.builder()
            .baseUrl("https://api.telegram.org/bot" + botToken)
            .build();
    }
}

TelegramAdapter

The adapter handles all communication with Telegram’s API:

src/main/java/com/acamus/telegrm/infrastructure/adapters/out/telegram/TelegramAdapter.java

public void sendMessage(TelegramChatId chatId, String text) {
    // Sends messages to Telegram via REST API
}

public List<Update> getUpdates(Long offset) {
    // Fetches new messages from Telegram
}

Troubleshooting

Bot not responding to messages

Possible causes:

Invalid token: Check your TELEGRAM_BOT_TOKEN in .env
Application not running: Ensure docker-compose up is active
Polling service not started: Check logs for scheduler initialization
Network issues: Verify your server can reach api.telegram.org

Solution:

# Check application logs
docker-compose logs -f

# Verify token is loaded
docker-compose logs | grep "telegram.bot-token"

401 Unauthorized error

This means your bot token is invalid or has been revoked.Solution:

Generate a new token with BotFather using /token
Update your .env file
Restart the application: docker-compose restart

Messages received but no AI response

The Telegram integration is working, but there’s an issue with AI generation.Check:

OpenRouter API key is valid (AI Configuration)
AI service logs for error messages
OpenRouter account has sufficient credits

Duplicate messages

If you’re receiving duplicate bot responses:Possible causes:

Multiple application instances running
Offset not being updated correctly in polling

Solution:

# Ensure only one instance is running
docker-compose down
docker-compose up --build

Bot Management Commands

Useful BotFather commands for managing your bot:

Command	Description
`/mybots`	List all your bots and manage them
`/token`	Generate a new token (revokes old one)
`/revoke`	Revoke bot token
`/setname`	Change bot name
`/setdescription`	Change bot description
`/setabouttext`	Change bot about text
`/setuserpic`	Change bot profile picture
`/setcommands`	Set bot command list
`/deletebot`	Delete your bot

Token Revocation: If you use /token to generate a new token, the old token becomes invalid immediately. Update your .env file before restarting the application.

Advanced Configuration

Adjusting Poll Frequency

The default polling interval is 1 second. To adjust this, modify:

src/main/java/com/acamus/telegrm/infrastructure/adapters/in/scheduler/TelegramPollingService.java

@Scheduled(fixedDelay = 2000) // Poll every 2 seconds
public void pollUpdates() {
    // ...
}

Shorter intervals provide faster response times but increase API calls. Telegram has rate limits, so don’t poll too frequently.

Next Steps

AI Configuration

Configure AI responses and behavior

Authentication

Secure your REST API endpoints

Environment Config

Review all configuration options

API Reference

Explore available API endpoints

Get Started

Architecture

Guides

Deployment

Telegram Bot Setup

Telegram Bot Setup

Overview

Creating Your Bot

Configuring Your Bot

Adding the Token to Your Application

Optional: Customize Bot Settings

Testing Your Bot

How Telegram Integration Works

Polling Architecture

Message Flow

Telegram Configuration in Code

application.yaml

TelegramConfig

TelegramAdapter

Troubleshooting

Bot Management Commands

Advanced Configuration

Adjusting Poll Frequency

Next Steps

AI Configuration

Authentication

Environment Config

API Reference

Build docs developers (and LLMs) love

Get Started

Architecture

Guides

Deployment

​Telegram Bot Setup

​Overview

​Creating Your Bot

​Configuring Your Bot

​Adding the Token to Your Application

​Optional: Customize Bot Settings

​Testing Your Bot

​How Telegram Integration Works

​Polling Architecture

​Message Flow

​Telegram Configuration in Code

​application.yaml

​TelegramConfig

​TelegramAdapter

​Troubleshooting

​Bot Management Commands

​Advanced Configuration

​Adjusting Poll Frequency

​Next Steps

AI Configuration

Authentication

Environment Config

API Reference

Build docs developers (and LLMs) love

Telegram Bot Setup

Overview

Creating Your Bot

Configuring Your Bot

Adding the Token to Your Application

Optional: Customize Bot Settings

Testing Your Bot

How Telegram Integration Works

Polling Architecture

Message Flow

Telegram Configuration in Code

application.yaml

TelegramConfig

TelegramAdapter

Troubleshooting

Bot Management Commands

Advanced Configuration

Adjusting Poll Frequency

Next Steps