https://github.com/ksilisk/telegram-bot-spring
Telegram Bot Spring Boot Starter
https://github.com/ksilisk/telegram-bot-spring
java spring-boot spring-boot-starter telegrambot
Last synced: 10 days ago
JSON representation
Telegram Bot Spring Boot Starter
- Host: GitHub
- URL: https://github.com/ksilisk/telegram-bot-spring
- Owner: ksilisk
- License: mit
- Created: 2025-10-11T16:03:46.000Z (7 months ago)
- Default Branch: master
- Last Pushed: 2026-02-14T18:54:59.000Z (3 months ago)
- Last Synced: 2026-02-15T02:55:33.300Z (3 months ago)
- Topics: java, spring-boot, spring-boot-starter, telegrambot
- Language: Java
- Homepage:
- Size: 306 KB
- Stars: 28
- Watchers: 1
- Forks: 7
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# **Telegram Bot Spring Boot Starter**
A modular Spring Boot framework for building Telegram bots on **Java 17** and Spring Boot ecosystem.
This project provides a structured, extensible foundation for Telegram bots that require clear routing, lifecycle management, transport abstraction, and optional observability.
---
## **Overview**
The framework is designed around a **transport-agnostic core pipeline** with explicit extension points.
It allows building anything from small bots to larger, long-lived applications without rewriting the architecture.
The project follows standard Spring Boot conventions and avoids hidden runtime magic.
---
## **Key characteristics**
- Modular, layered architecture
- Transport-independent core
- Explicit update processing pipeline
- Multiple delivery modes (long polling, webhook)
- Pluggable HTTP client implementations
- Optional metrics and observability
- Spring Boot auto-configuration
- Runnable example applications
---
## **Quick start**
### **1. Add dependency**
```xml
io.github.ksilisk
telegram-bot-spring-boot-starter
0.7.0
```
By default, this enables **long polling** transport.
---
### **2. Configure bot token**
```yaml
telegram:
bot:
token: ${TELEGRAM_BOT_TOKEN}
```
---
### **3. Implement a handler**
```java
@Component
public class StartCommandHandler implements CommandUpdateHandler {
private final TelegramBotExecutor executor;
public StartCommandHandler(TelegramBotExecutor executor) {
this.executor = executor;
}
@Override
public void handle(Update update) {
executor.execute(
new SendMessage(Updates.chatId(update), "Hello")
);
}
@Override
public Set commands() {
return Set.of("/start");
}
}
```
Run the Spring Boot application to start the bot.
---
## **Processing model**
Conceptually, updates are processed as follows:
```
Telegram
↓
Ingress (long polling / webhook)
↓
Delivery (thread pool)
↓
Interceptors
↓
Dispatcher
↓
Routers
↓
Handlers
↓
(No-match strategies / Exception handlers)
```
Application code usually interacts only with **handlers**, **rules**, and optional interceptors.
---
## **Project structure**
The repository is organized into focused modules:
|**Module**|**Description**|
|---|---|
|telegram-bot-core|Core processing pipeline, routing, handlers, SPI|
|telegram-bot-long-polling|Long polling transport (default)|
|telegram-bot-webhook|Webhook transport (opt-in)|
|telegram-bot-observability|Metrics and observability integration|
|telegram-bot-spring-boot-autoconfigure|Spring Boot auto-configuration|
|telegram-bot-spring-boot-starter|Starter dependency|
|telegram-bot-dependencies|BOM for dependency management|
|examples/|Runnable sample applications|
Each module contains a dedicated README with detailed documentation.
---
## **Transport selection**
The framework supports multiple update ingestion modes.
### **Built-in transports**
- **LONG_POLLING** (default)
Receives updates via Telegram long polling. Requires no HTTP endpoint.
- **WEBHOOK**
Receives updates via HTTPS callbacks from Telegram.
Requires an explicit dependency and a public HTTPS endpoint.
- **NO_INGRESS**
Runs the bot without any update ingress.
Incoming updates from Telegram are not received. Suitable for outbound-only bots,
scheduled notifications, and integration-driven use cases.
### **Custom ingress**
- **CUSTOM**
Disables built-in transports and allows applications to provide their own UpdateIngress implementation.
This mode is intended for advanced use cases, such as:
- custom gateways or proxies
- message queues or event streams
- testing and replaying updates
- non-standard Telegram delivery mechanisms
Transport selection is controlled via:
```yaml
telegram:
bot:
mode: LONG_POLLING | WEBHOOK | CUSTOM | NO_INGRESS
```
In CUSTOM mode, application startup will fail if no UpdateIngress bean is provided.
---
## **Configuration model**
Configuration is based on Spring Boot @ConfigurationProperties and follows a single, consistent prefix:
```
telegram.bot.*
```
Transport-specific and optional modules introduce their own nested namespaces.
---
## **Examples**
The [/examples](examples) directory contains standalone Spring Boot applications demonstrating:
- minimal long polling setup
- webhook configuration and lifecycle
- routing and handler composition
Each example can be run independently.
---
## **Design principles**
- Explicit over implicit
- Interfaces over implementations
- Transport-agnostic core
- Predictable lifecycle and threading
- Production-oriented defaults
---
## **Documentation entry points**
- **Core architecture**: [telegram-bot-core/README.md](telegram-bot-core/README.md)
- **Long polling transport**: [telegram-bot-long-polling/README.md](telegram-bot-long-polling/README.md)
- **Webhook transport**: [telegram-bot-webhook/README.md](telegram-bot-webhook/README.md)
- **Observability**: [telegram-bot-observability/README.md](telegram-bot-observability/README.md)
---