Telegram Bot API

1. Przegląd koncepcji i problem systemowy

Tworzenie interfejsów dla agentów AI napotyka wysoki próg wejścia: budowanie natywnych aplikacji mobilnych wymaga długotrwałego procesu przeglądu w App Store/Google Play, a interfejsy webowe wymagają implementacji autoryzacji, powiadomień push oraz responsywnego designu.

Telegram Bot API oferuje gotową infrastrukturę transportową oraz cross-platformowy interfejs użytkownika z bazą ponad 900 milionów osób. Bot działa jako specjalne konto bez numeru telefonu, zarządzane za pomocą żądań RESTful HTTPS lub zdarzeń Webhook. Dla agentów LLM Telegram stał się de facto głównym kanałem interakcji dzięki natywnej obsłudze streamingu wiadomości (poprzez edycję), przesyłaniu notatek głosowych, niestandardowym klawiaturom oraz wbudowanym aplikacjom webowym (Telegram Mini Apps).

+---------------+        HTTPS Webhook        +-------------------+
|    Klient     | <=========================> | Serwery Telegrama |
| (iOS/Android) |                             | (api.telegram.org)|
+---------------+                             +---------+---------+
                                                        |
                                                        | HTTPS POST /webhook
                                                        v
                                              +-------------------+
                                              | Własny backend    |
                                              | (Reverse Proxy /  |
                                              |  FastAPI / grammY) |
                                              +---------+---------+
                                                        |
                                                        v
                                              +-------------------+
                                              | Agent AI / LLM    |
                                              +-------------------+

2. Taksonomia architektoniczna i model mentalny

Architektura integracji z Telegram Bot API dzieli się w zależności od metody pobierania aktualizacji (Updates):

1. Long Polling (getUpdates):
   • Proces klienta utrzymuje otwarte połączenie HTTP z api.telegram.org przez 30–50 sekund, oczekując na nowe zdarzenia.
   • Zalety: Działa lokalnie bez potrzeby posiadania białej statycznej adresu IP, domeny ani certyfikatów SSL.
   • Wady: Wysokie zużycie transferu, blokowanie socketów, brak możliwości poziomego skalowania wielu instancji bez duplikowania przetwarzania zdarzeń.
2. Webhooks (setWebhook):
   • Serwery Telegram natychmiast wysyłają żądanie POST z payloadem JSON do publicznego endpointu HTTPS Twojego serwera po wystąpieniu dowolnego zdarzenia.
   • Zalety: Zerowe opóźnienie, maksymalna efektywność zasobów serwera, możliwość wykorzystania architektury Serverless (Cloudflare Workers, AWS Lambda).
   • Wymagania: Posiadanie ważnego certyfikatu TLS/SSL (Let's Encrypt lub self-signed) oraz ochrona endpointu za pomocą secret_token.
3. Local Bot API Server (Self-hosted Telegram Bot API):
   • Kompilacja oficjalnego serwera C++ telegram-bot-api na własnym sprzęcie.
   • Usuwa ograniczenie rozmiaru przesyłanych plików do 20 MB (podnosząc limit do 2 GB) oraz umożliwia wysyłanie plików przez lokalne sockety UNIX z zerowym czasem kopiowania.

3. Pipeline techniczny i mechanika wewnętrzna

Konfiguracja produkcyjnego webhooka z tokenem zabezpieczającym

Aby zagwarantować, że przychodzące żądanie HTTP pochodzi właśnie z serwerów Telegram, konieczne jest skonfigurowanie nagłówka X-Telegram-Bot-Api-Secret-Token:

curl -F "url=https://bot.example.com/api/v1/telegram-webhook" \
     -F "max_connections=100" \
     -F "secret_token=d98f7e2a4bc108e4fae8910bc472" \
     -F "allowed_updates=[\"message\",\"callback_query\"]" \
     https://api.telegram.org/bot<BOT_TOKEN>/setWebhook

Pipeline przetwarzania żądań (TypeScript / grammY)

import { Bot, webhookCallback } from "grammy";
import { limit } from "@grammyjs/ratelimiter";

const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);

// 1. Вбудований рейт-лімітер для користувачів
bot.use(
  limit({
    timeFrame: 2000,
    limit: 3,
    onLimitExceeded: async (ctx) => {
      await ctx.reply("Забагато запитів. Зачекайте декілька секунд.");
    },
  })
);

// 2. Обробка текстових команд та запуск AI-пайплайну
bot.command("ask", async (ctx) => {
  const query = ctx.match;
  if (!query) return ctx.reply("Вкажіть запитання для агента.");

  // Імітація статусу друку під час генерації відповіді
  await ctx.replyWithChatAction("typing");

  const response = await callAgentOrchestrator(query, ctx.from.id);
  await ctx.reply(response, { parse_mode: "HTML" });
});

export default webhookCallback(bot, "std/http", {
  secretToken: process.env.TELEGRAM_WEBHOOK_SECRET,
});

4. Praktyczne scenariusze inżynieryjne w środowisku produkcyjnym

01. Asystent głosowy z transkrypcją w czasie rzeczywistym

Użytkownik wysyła wiadomość głosową (.ogg / Opus). Backend bota otrzymuje file_id, pobiera plik audio przez Bot API, konwertuje go do formatu PCM za pomocą ffmpeg i przekazuje do Whisper API lub lokalnego modelu. Uzyskany tekst trafia do pipeline'u RAG, a bot zwraca zwięzłą, ustrukturyzowaną odpowiedź lub syntezowany głos z powrotem do czatu.

02. Interaktywny deployment i kontrola DevOps poprzez Inline-klawiatury

Bot jest podłączony do klastra Kubernetes / Coolify. W przypadku awarii poda lub alertu w Prometheus bot generuje alert na prywatnym kanale deweloperskim z przyciskami: [Rollback], [View Logs], [Scale Replicas]. Kliknięcie wywołuje callback_query, który identyfikuje inżyniera po ID Telegram, sprawdza jego uprawnienia na liście white-list i uruchamia bezpieczny skrypt bezpośrednio z telefonu.

03. Telegram Mini App (TMA) dla dashboardów analitycznych

Zamiast przeciążać czat tabelami tekstowymi, bot otwiera aplikację Web App wewnątrz Telegrama przez Webview. Frontend napisany w React/Next.js otrzymuje kryptograficznie podpisane dane initData, które backend waliduje za pomocą HMAC-SHA256 z tokenem bota. Użytkownik interaguje z interaktywnymi wykresami bez konieczności wprowadzania loginu i hasła.

5. Pułapki, typowe błędy i bezpieczeństwo

1. Kompromitacja BOT_TOKEN: Token bota daje pełną kontrolę nad odczytem wiadomości i zarządzaniem czatami. Nigdy nie commituj tokenów do publicznych repozytoriów. W przypadku wycieku natychmiast odwołaj token przez @BotFather (/revoke).
2. Znaki specjalne w MarkdownV2: Format MarkdownV2 wymaga ścisłego escapowania 18 znaków (_, *, [, ], (, ), ~, `, >, #, +, -, =, |, {, }, ., !). Jeśli LLM wygeneruje niedopasowany symbol lub kropkę bez slash'a, Telegram zwróci błąd 400 Bad Request: can't parse entities, a wiadomość nie dotrze do użytkownika. Zaleca się używanie trybu parsowania HTML lub niezawodnych bibliotek formatujących.
3. Blokowanie Event Loop przez synchroniczne przetwarzanie: Telegram wymaga odpowiedzi 200 OK na przychodzący webhook w ciągu kilku sekund. Jeśli generowanie odpowiedzi przez LLM trwa 15 sekund, a backend czeka na zakończenie przed wysłaniem statusu webhooka, Telegram uzna dostarczenie za nieudane i ponowi żądanie POST, powodując lawinowe mnożenie się identycznych generacji. Zawsze potwierdzaj odbiór webhooka natychmiastowo, a przetwarzanie przenieś do zadań w tle (Background Tasks / Message Queue).