Проще говоря, outbox - это почтовый ящик исходящих сообщений бота. В нем видно, что нужно отправить, кому, каким методом, с каким текстом или payload, сколько уже было попыток, какая последняя ошибка и можно ли повторить отправку.
Для AI-агента Telegram outbox особенно полезен, потому что ответ может готовиться долго. Webhook должен быстро вернуть Telegram 200 OK, а генерация AI-ответа, tool calling, проверка прав и отправка сообщения могут выполняться асинхронно. Outbox помогает не потерять финальный ответ и не отправить его дважды.
Обычно у записи outbox есть статусы: pending, sending, sent, failed, retry, cancelled. Также полезны поля chat_id, user_id, message type, text, parse mode, reply_markup, idempotency key, trace id, attempt count, next_retry_at и telegram_message_id после успешной отправки.
Главная ошибка - отправлять исходящие сообщения без дедупликации. Если worker упал после sendMessage, но до записи результата, повторная попытка может отправить пользователю дубль. Поэтому для важных сценариев используют idempotency key, outbox status, блокировки worker и аккуратные правила retry.
Telegram outbox также помогает соблюдать лимиты. Если нужно отправить много уведомлений, worker может дозировать отправку, обрабатывать 429 Too Many Requests, учитывать retry_after и не блокировать основной webhook. Для сообщений с персональными данными важно хранить payload ограниченное время и маскировать чувствительные поля в логах.
Примеры
- AI-агент сгенерировал ответ клиенту. Backend создал запись в telegram outbox, worker отправил sendMessage и сохранил telegram_message_id.
- Telegram API вернул 429 Too Many Requests. Outbox поставил статус retry и запланировал повторную отправку по retry_after.
- Worker упал после генерации ответа. Сообщение осталось в pending, поэтому другой worker отправил его позже.
- Пользователь нажал кнопку дважды. Idempotency key не дал создать два одинаковых исходящих сообщения.
- Нужно отправить 5 000 уведомлений. Outbox дозирует отправку и не перегружает Bot API.
Где используется
- надежная отправка ответов Telegram-бота
- асинхронные AI-ответы после webhook
- retry при ошибках Telegram Bot API
- защита от дублей сообщений
- массовые уведомления с учетом rate limits
- логирование исходящих сообщений бота
- связь ответа с trace и agent session
- отложенная отправка сообщений
- отмена сообщений перед отправкой при смене статуса сценария
Связанные термины
Частые вопросы
Что такое Telegram outbox простыми словами?
Это очередь исходящих сообщений бота. В нее приложение кладет ответы и уведомления, а отдельный worker отправляет их в Telegram и фиксирует результат.
Зачем Telegram-боту outbox?
Чтобы не терять сообщения при сбоях, повторять отправку при временных ошибках, контролировать лимиты Telegram API и не отправлять дубли.
Какие статусы нужны для telegram outbox?
Обычно используют pending, sending, sent, retry, failed и cancelled. Также полезно хранить attempt count, next_retry_at и последнюю ошибку.
Как outbox связан с Telegram webhook?
Webhook быстро принимает update и возвращает 200 OK. Долгая обработка и отправка ответа идут позже: AI готовит текст, создает запись в outbox, worker отправляет сообщение.
Как избежать двойной отправки сообщений?
Нужны idempotency key, блокировка записи при отправке, хранение статуса sent и аккуратная обработка ситуации, когда Telegram ответил успешно, но worker упал до записи результата.
