Wiki/Telegram/Message Flow

Поток сообщений Telegram

Как сообщения проходят через бота

Диаграмма потока (Private Chat)

USER
"Привет, как дела?"
↓

Telegram API

Long-polling (timeout: 30s) → Receive Update object
↓

Message Normalization

Extract
chat_id, user_id, text
Detect
message_type
Context
reply_to, thread_id
Forward
forward_from
↓

Queue (chat_queue)

Global
max 2 concurrent
Per-chat
max 8 pending
If full
"Занят, позже"
↓

Auth & RBAC

Get/create user
Check tier
Rate limits
Ban check
↓

Command Handler

/start, /help, /status

Chat Handler

Simple chat

Operator Handler

Complex tasks
↓

DB Operations

Save message
Load context
Query policy
Create run
↓

LLM Processing

🤖
Agent Select
→
🧠
Prompt Assembly
→
🧠
LLM Call
→
🗄️
Log
↓

Response Assembly

Parse LLM
Format
Split >4096
Update status
↓

Telegram Send

📨
sendMessage
→
🗄️
Save to DB
→
⚡
Log Event
↓
USER
"Привет! Всё отлично..."

Типы сообщений

Text Message

Обычное текстовое сообщение

{
  "message_id": 123,
  "from": {"id": 123456, "username": "user"},
  "chat": {"id": 123456, "type": "private"},
  "text": "Привет!",
  "date": 1709500000
}

Voice Message

Голосовое → транскрибация через Whisper

{
  "voice": {
    "file_id": "AwADBAADbQ...",
    "duration": 5,
    "mime_type": "audio/ogg"
  }
}

# Flow: download → whisper → text

Command

Команда (/start, /help, /status...)

{
  "text": "/help",
  "entities": [{
    "type": "bot_command",
    "offset": 0,
    "length": 5
  }]
}

# Route to CommandHandler

Reply

Ответ на сообщение бота

{
  "reply_to_message": {
    "message_id": 122,
    "from": {"id": BOT_ID}
  }
}

# Context: reply_to for threading

Групповые чаты

GROUP
"@bot_name напомни мне через 5 минут"
↓

Addressing Check

@bot_name
Mention
Reply to bot
Thread
/cmd@bot_name
Command
If NO → IGNORE(don't respond to every message!)
↓
(if addressed)
↓

Group Context

Load group info
Check permissions
Load context
↓
[Same flow as private chat]
↓

Response in Group

reply_to_message_id
@user mention
Markdown

⚠️ Важно: Addressing в группах

В групповых чатах бот отвечает ТОЛЬКО когда:

  • • Бот упомянут: @bot_name
  • • Команда с упоминанием: /cmd@bot_name
  • • Ответ на сообщение бота (reply)

Это предотвращает spam и гарантирует, что бот не отвечает на каждое сообщение в группе.

Smart Messages

Smart Messages — это сообщения с inline-кнопками для взаимодействия с пользователем. Определяются в process_rules.md.

Пример: Web Search Result

Результаты поиска:
Нашёл 5 источников по вашему запросу...
📖 Подробнее🔄 Повторить⭐ Сохранить
# Smart message structure
{
  "text": "Результаты поиска...",
  "parse_mode": "Markdown",
  "reply_markup": {
    "inline_keyboard": [
      [
        {"text": "📖 Подробнее", "callback_data": "expand:run_id"},
        {"text": "🔄 Повторить", "callback_data": "redo:run_id"}
      ],
      [
        {"text": "⭐ Сохранить", "callback_data": "save:run_id"}
      ]
    ]
  }
}

Rate Limits

TierMessages/dayLLM calls/dayProcesses/day
Free1005010
Paid1000500100
OwnerUnlimitedUnlimitedUnlimited

Обработка ошибок

Telegram Errors

  • •429 Too Many Requests — exponential backoff
  • •403 Forbidden — user blocked bot
  • •400 Bad Request — invalid message format
  • •Network errors — retry with backoff

User-Facing Errors

  • •"Произошла ошибка, попробуйте позже"
  • •"Сервис временно недоступен"
  • •"Превышен лимит запросов"
  • •Never expose internal errors to user

Связанные страницы

Python Bridge
Архитектура Bridge
Scenarios
Послойная отработка
Processes
Процессы

Навыки для понимания

Telegram Bot APIMessage handlingQueue patternsError handling