Telegram getUpdates offset: как избежать дублей и потери обновлений

Telegram считает обновление подтверждённым, когда вы вызываете getUpdates с offset, превышающим его update_id. Само получение ответа ещё не является подтверждением. Чтобы не потерять работу, сначала надёжно сохраните возвращённые обновления и только затем отправляйте следующий запрос с большим offset. Для безопасного перезапуска сохраняйте следующую позицию вместе с данными, а дедупликацию отделяйте от бизнес-обработки.

Главное

• offset — граница подтверждения, а не номер страницы или количество сообщений.
• Продвигайте её только после сохранения всех обновлений, которые будут подтверждены.
• Для каждого бота оставляйте один активный процесс опроса; масштабируйте обработчики за ним.
• Надёжный входящий журнал защищает приём данных, но внешним действиям нужна собственная стратегия повторов.

Здесь предполагается, что вы уже выбрали polling. Если webhook всё ещё настроен, сначала используйте инструкцию переключения между getUpdates и setWebhook. Эта статья посвящена фиксации данных между успешными запросами, а не выбору способа доставки.

Что именно подтверждает offset в getUpdates

Официальный справочник Telegram Bot API определяет offset как идентификатор первого обновления, которое нужно вернуть. Без этого параметра выдача начинается с самого раннего неподтверждённого обновления. Последующий вызов с offset выше идентификатора обновления подтверждает его.

Условный пример: ответ содержит обновления 8100, 8101 и 8102. Следующий вызов с offset=8103 подтвердит все три, даже если приложение обработало только последнее. Telegram не проверяет вашу базу данных и не ждёт завершения операции в CRM.

Упрощение	Риск	Более безопасный вариант
Записать максимальный ID до сохранения пакета	После перезапуска можно пропустить несохранённые обновления	Фиксировать входящие данные и следующий offset вместе
Продвигать offset после самой быстрой параллельной задачи	Более ранние незавершённые обновления тоже будут подтверждены	Опираться на сохранение данных, а не порядок завершения обработчиков
Хранить offset только в памяти	Перезапуск уничтожает локальную контрольную точку	Загружать постоянную контрольную точку для конкретного бота
Исправлять дубли отрицательным offset	Более ранние обновления очереди будут отброшены	Проверить владельца опроса и дедупликацию

Telegram прямо указывает: отрицательный offset выбирает обновления с конца очереди, а предыдущие обновления забываются. Это не механизм восстановления нужных рабочих данных.

Разделите прогресс приёма и завершение работы

Практичная схема включает две записи, принадлежащие приложению: входящий журнал с полным обновлением и контрольную точку со следующим offset. Это понятия локального хранилища, а не дополнительные поля Telegram API.

Уникальный ключ входящей записи составьте из стабильного идентификатора бота и update_id. Не используйте сам bot token как ключ базы данных и не выводите его в журналы. Сохраняйте все возвращённые типы обновлений, даже если текущий обработчик их пока не понимает. Классификацию можно выполнить после приёма.

Рекомендуемая последовательность транзакции:

Прочитать сохранённый следующий offset этого бота.
Вызвать getUpdates с этим offset.
Если пакет пуст, оставить контрольную точку без изменений.
Иначе начать транзакцию базы данных:
  Вставить каждое обновление, не добавляя повторно существующие уникальные ключи.
  Сохранить max(update_id в пакете) + 1 как следующий offset.
Зафиксировать транзакцию.
Только после фиксации выполнить следующий запрос.
Обрабатывать сохранённые обновления отдельными воркерами.

Это проектный псевдокод, а не готовый клиент. Он предполагает единственного активного владельца опроса, надёжное транзакционное хранилище и ограничение уникальности. При сбое транзакции не продвигайте позицию: повторите работу с сохранённой контрольной точки. Нельзя перехватить ошибку записи и продолжить с увеличенным offset.

Если входящий журнал и контрольная точка находятся в разных системах, такой атомарности автоматически нет. Нужны продуманная надёжная передача и сверка состояния: две успешные записи сами по себе не становятся одной транзакцией.

Проверьте границы сбоя

Ниже — предлагаемые приёмочные проверки, а не результаты проведённых испытаний.

Момент остановки	Ожидаемое восстановление
После получения пакета, до фиксации	Загрузить старую позицию; допустить повторную доставку
Во время транзакции	После отката не должно остаться частично обновлённой контрольной точки
После фиксации, до следующего запроса	Загрузить новую позицию; сохранённая работа остаётся доступной
После внешнего действия, до записи о завершении	Использовать сверку или идемпотентность внешней системы; входящего ключа недостаточно

Повторное обновление должно сопоставляться с существующей входящей записью. Но наличие записи не означает завершения бизнес-операции: воркер должен находить и повторять сохранённую незавершённую работу. И наоборот, повторная доставка не должна автоматически запускать ещё один ответ или изменение в CRM.

При развёртывании явно передавайте право опроса. Забытый процесс разработки или ручной диагностический запрос с большим offset может подтвердить обновления вне вашего пути сохранения. Не позволяйте диагностике, которую считаете «только чтением», менять рабочую позицию.

Ограничения и граница UnifyPort

Telegram указывает, что входящие обновления хранятся не дольше 24 часов. Контрольная точка не создаёт бессрочный архив. Уменьшение offset не восстановит подтверждённые или просроченные обновления. Периоды простоя нужно проверять на возможную потерю данных.

Если нужен входящий поток существующего аккаунта или общая очередь нескольких каналов, сначала прочитайте сравнение Telegram Bot API webhook и унифицированного входящего webhook. Неофициальный интерфейс UnifyPort использует нормализованные события, например message.received, а не позицию опроса вашего бота.

Справочник доставки UnifyPort описывает отдельный контракт подтверждения. Настройте signing_secret, проверьте X-Device-Signature через HMAC-SHA256 от временной метки, точки и исходных байтов запроса. Затем надёжно сохраните событие и только после этого верните успешный ответ. При повторе обычного события сохраняется X-Device-Event-Id. У UnifyPort нет REST API чтения истории сообщений и гарантированного повтора пропущенных данных. Это не сервис восстановления подтверждённых обновлений Bot API.

Частые вопросы

Почему getUpdates постоянно возвращает одни и те же обновления?

Проверьте, действительно ли следующий запрос использует offset выше их update_id и загружается ли сохранённая позиция после перезапуска. Безопасно удаляйте дубли, а не очищайте очередь.

Нужно ждать завершения AI-задачи или операции CRM?

Не обязательно, если полное обновление надёжно сохранено, а задачу можно повторить независимо. Хранение только в памяти не является надёжной передачей работы.

Гарантирует ли схема отправку ответа ровно один раз?

Нет. Атомарное сохранение устраняет один класс потерь, но отправка может завершиться до записи результата воркером. На этой границе тоже нужны идемпотентность или сверка.

Следующий шаг и источники

Проверьте цикл опроса на границе фиксации транзакции. Если вы реализуете приём для подключённого аккаунта обмена сообщениями, используйте контракт доставки webhook, не перенося в него логику offset из Bot API.

• Telegram Bot API: getUpdates и Getting updates, проверено 2026-09-19.
• UnifyPort: доставка webhook и проверка подписи.