Telegram Bot Integration
Relevant source files
The following files were used as context for generating this wiki page:
- apps/api/src/main/kotlin/com/briefy/api/application/telegram/TelegramIngestionProcessor.kt
- apps/api/src/main/kotlin/com/briefy/api/api/TelegramIntegrationController.kt
- apps/api/src/main/kotlin/com/briefy/api/application/telegram/TelegramWebhookService.kt
- apps/api/src/main/kotlin/com/briefy/api/application/telegram/TelegramLinkService.kt
- apps/api/src/main/kotlin/com/briefy/api/config/TelegramProperties.kt
- apps/web/src/routes/settings/index.tsx
The Telegram Bot Integration provides a seamless bridge between the Telegram messaging platform and the Briefy knowledge management system. It allows users to ingest web content into their Briefy library by simply forwarding messages or sending URLs directly to a dedicated Telegram bot.
The integration facilitates two primary workflows: account linking and content ingestion. Users link their Briefy accounts via a secure one-time code generated in the web application. Once linked, any URL sent to the bot is automatically extracted, normalized, and stored as a "Source" in the user's Briefy account.
System Architecture
The integration follows a webhook-based architecture where Telegram notifies the Briefy API of incoming messages. The backend processes these messages through a pipeline involving link verification, URL extraction, and asynchronous ingestion jobs.
Component Overview
| Component | Responsibility |
|---|---|
TelegramWebhookController | Entry point for Telegram API callbacks; validates secret tokens. |
TelegramWebhookService | Routes incoming messages to either command handlers or ingestion flows. |
TelegramLinkService | Manages the lifecycle of the connection between Briefy users and Telegram IDs. |
TelegramIngestionProcessor | Handles the business logic of converting message text into Briefy Sources. |
TelegramBotGateway | Infrastructure component used to send replies back to the user on Telegram. |
Sources: apps/api/src/main/kotlin/com/briefy/api/api/TelegramIntegrationController.kt, apps/api/src/main/kotlin/com/briefy/api/application/telegram/TelegramWebhookService.kt
Integration Flow Diagram
The following diagram illustrates the flow from a user sending a message to the bot to the content being created in the database.
Account Linking Process
Before a user can ingest content, they must link their Telegram account to their Briefy identity. This is handled through a "Link Code" mechanism.
- Code Generation: The user visits the Briefy settings page and requests a link code. The system generates a random 8-character readable code (e.g.,
ABCDEFGH) and stores its SHA-256 hash. - Bot Command: The user sends
/link CODEto the Telegram bot. - Verification: The
TelegramLinkServicehashes the provided code, matches it against unexpired/unused codes in the database, and creates aTelegramLinkrecord mapping thetelegramUserIdto the BriefyuserId.
Sources: apps/api/src/main/kotlin/com/briefy/api/application/telegram/TelegramLinkService.kt:41-59, apps/api/src/main/kotlin/com/briefy/api/application/telegram/TelegramWebhookService.kt:100-115
Linking Sequence
Content Ingestion
Once linked, the bot processes standard text messages. It uses a TelegramUrlExtractor to identify URLs within the message body or captions.
Processing Logic
- URL Limit: A maximum of 10 URLs are processed per message. Subsequent URLs are skipped to prevent abuse.
- Normalization: Every extracted URL is normalized using the
Url.normalize()utility. - Deduplication: The system checks if the source already exists for that user before creating a new one.
- Status Reporting: The bot replies with a summary including the titles of successfully created sources and links to the Briefy web application.
Sources: apps/api/src/main/kotlin/com/briefy/api/application/telegram/TelegramIngestionProcessor.kt:33-65, apps/api/src/main/kotlin/com/briefy/api/application/telegram/TelegramWebhookService.kt:133
Configuration and Security
The integration relies on environment-specific properties for connectivity and security validation.
Telegram Properties
| Property | Description | Default |
|---|---|---|
telegram.integration.enabled | Global toggle for the integration. | false |
telegram.bot.token | Authentication token provided by BotFather. | - |
telegram.webhook.secret-token | Token expected in X-Telegram-Bot-Api-Secret-Token header. | - |
telegram.ingestion.worker.batch-size | Number of jobs processed per worker cycle. | 5 |
Sources: apps/api/src/main/kotlin/com/briefy/api/config/TelegramProperties.kt:10-40, apps/api/src/main/resources/application.yml:195-210
Security Constraints
- Private Chats Only: The bot only responds to messages sent in "private" chat types; group messages are ignored for security and privacy.
- Webhook Authorization: The
TelegramWebhookControllerrejects any request that does not include the correctX-Telegram-Bot-Api-Secret-Tokenconfigured in the system. - Unique Linking: A Telegram account can only be linked to one Briefy account at a time, and vice versa.
Sources: apps/api/src/main/kotlin/com/briefy/api/application/telegram/TelegramWebhookService.kt:35-40, apps/api/src/main/kotlin/com/briefy/api/api/TelegramIntegrationController.kt:90-100, apps/api/src/main/kotlin/com/briefy/api/application/telegram/TelegramLinkService.kt:113-120
User Commands
The bot supports the following standard slash commands:
/startor/help: Displays bot instructions and available commands./link <CODE>: Connects the Telegram account to Briefy./unlink: Removes the existing connection between Telegram and Briefy.
Sources: apps/api/src/main/kotlin/com/briefy/api/application/telegram/TelegramWebhookService.kt:95-125
The Telegram Bot Integration significantly reduces the friction of capturing information by allowing users to use a tool they already have open for daily communication. By handling URL extraction and account linking securely, it provides a robust entry point for the Briefy ingestion pipeline.