Бот перестал отвечать: диагностика за 15 минут

Бот молчит, а клиенты пишут

Утром клиент пишет, что записаться через бота нельзя. Вы шлёте /start, в ответ тишина. Администратор не помнит, когда видел последнюю заявку, а исполнитель на связи только вечером. Заявки в это время уходят к тем, кто ответил.

Сначала нужно понять, на каком звене оборвалась цепочка. Код читать не придётся, нужен порядок проверок, он годится и владельцу, и исполнителю. Похожий разбор для сайта есть в статье про диагностику сайта за 10 минут.

Как бот получает сообщения

Сообщение клиента попадает на платформу, а не на ваш сервер. Дальше бот забирает его одним из двух способов, и они исключают друг друга. При long polling бот сам по кругу спрашивает платформу, нет ли нового. При вебхуке платформа сама шлёт POST-запрос на адрес вашего сервера. В Telegram, пока вебхук установлен, опрос не работает, и непрочитанное хранится не дольше 24 часов. В MAX то же самое: вебхук оформляет POST /subscriptions, опрос идёт через GET /updates, а при активной подписке опрос не работает.

Цепочка получается такая: платформа, ваш сервер, процесс бота, база и внешние сервисы, ответ через API. Сбой на любом звене выглядит как тишина.

Шесть проверок по порядку

Шаг 1, сервер и процесс (2 минуты). Посмотрите, запущена ли служба бота, и прочитайте последние строки её журнала: упавший процесс обычно оставляет там причину. Проверьте диск, переполненный роняет и базу, и журнал.

Шаг 2, токен (1 минута). Откройте в браузере адрес https://api.telegram.org/bot<токен>/getMe. В документации это метод проверки токена. Пришёл JSON с данными бота, токен жив. Пришла ошибка, скорее всего на сервере другой токен: новый выдаёт команда /token в BotFather. В MAX аналог GET /me, токен идёт в заголовке Authorization, а при неверном приходит 401. У старого кода проверьте две вещи: MAX больше не принимает токен в параметрах адреса и просит слать запросы на домен platform-api2.max.ru.

Шаг 3, вебхук (3 минуты). Вызовите getWebhookInfo, параметры не нужны. Смотрите на три поля. Пустой url означает, что вебхука нет. Растущий pending_update_count означает, что сервер не принимает сообщения. Поля last_error_date и last_error_message называют время и причину последней ошибки доставки. По документации Telegram, порт должен быть 443, 80, 88 или 8443, сертификат действующим, имя в нём совпадать с доменом, а редиректы не поддерживаются. На неудачную доставку Telegram повторяет запрос «разумное число раз» и сдаётся.

Две копии бота с одним токеном дают конфликт, обычно с кодом 409. Так бывает, когда тестовую копию запустили на ноутбуке с боевым токеном. Код 409 в документации Bot API я не нашёл, он из практики.

В MAX подписки показывает GET /subscriptions. Пустой список после простоя возможен: доставку повторяют до 10 раз (через 60, 150, 375 секунд и дальше), а если 8 часов нет ответа 200, бот отписывается сам и подписку нужно оформить заново. Требования к адресу: HTTPS, порт 443, сертификат доверенного центра или Минцифры, самоподписанные не принимаются, ответ 200 за 30 секунд.

Шаг 4, лимиты и блокировки (3 минуты). При превышении лимита Telegram отвечает ошибкой 429 с полем retry_after, числом секунд до повтора. По FAQ Telegram, в один чат не стоит слать чаще раза в секунду, в группу больше 20 в минуту, а рассылка упирается примерно в 30 сообщений в секунду. Если бот молчит для отдельных людей, они могли его заблокировать: в личных чатах Telegram присылает боту обновление my_chat_member при блокировке и разблокировке. Тексты ошибок отправки в закрытый чат по документации я не проверял. В MAX на dev.max.ru указан предел 30 запросов в секунду на platform-api2.max.ru, а код 429 есть в списке ошибок. Как MAX сообщает время ожидания, я не нашёл.

Шаг 5, права в чате (1 минута). В группе бот с включённым режимом приватности видит лишь команды в его адрес и ответы на его сообщения. Администраторы и боты с выключенным режимом видят всё, кроме сообщений других ботов. Чтобы публиковать в канале, боту нужны права администратора. В MAX события из групп и каналов бот получает тоже только как администратор.

Шаг 6, зависимости (5 минут). Процесс жив, getMe проходит, вебхук чист, ответа нет. Значит бот принимает сообщение и падает при обработке. Ищите в журнале ошибки базы, платёжки, внешнего API, например закончились деньги на ключе сервиса. Почему связки ломаются, рассказано в статье про поддержку ботов и интеграций.

Как узнавать первым

В одном из моих ботов стоит отдельный сторож. Раз в 2 минуты systemd-таймер запускает скрипт, который проверяет службу, метку времени планировщика (не обновлялась больше 180 секунд, значит бот завис и перезапускается), адрес /health изнутри и снаружи, память, диск (порог 85 процентов), срок сертификата, а раз в сутки целостность базы. Что можно, он чинит сам и пишет администраторам, одну проблему не чаще раза в час.

Слабое место такого сторожа в том, что сообщение идёт через тот же Telegram. Если сломан токен, оно не дойдёт, поэтому нужен второй канал, например почта или MAX. Минимум без разработки это внешняя проверка адреса раз в 5 минут, как в статье про Uptime Kuma, а общая картина в разборе про отказоустойчивость.

Что сделать сегодня. Выясните, где лежит токен и у кого есть доступ к серверу. Запишите три проверки (getMe, getWebhookInfo, журнал) рядом с доступами и включите проверку раз в 5 минут. Перед запуском нового бота пригодится чек-лист приёмки.

Что важно учесть

Порядок находит причину не всегда. Не проверено: тексты ошибок 403 и 400 при отправке в закрытый чат, код 409 по документации, лимит запросов в MAX, перевыпуск токена в MAX и срок хранения событий при long polling в MAX.

Автоперезапуск лечит симптом, и если бот падает раз в сутки, причину нужно искать. Доступы к платформе и серверу должны быть на вас, иначе проверять будет нечем.

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

Бот отвечает в личке, но молчит в группе. Что смотреть?

Режим приватности и права. С включённым режимом бот видит только команды в его адрес и ответы на его сообщения. Отключите режим в BotFather или сделайте бота администратором.

Что лучше, вебхук или опрос?

Telegram лучшего способа не называет, а MAX для боевой работы рекомендует вебхук. Вебхуку нужны домен, сертификат и открытый порт, опросу нет.

Пропадут ли сообщения, пока бот лежал?

Не сразу. Telegram хранит непрочитанное до 24 часов. В MAX через 8 часов без ответа подписка снимается. После суток простоя часть сообщений теряется.

Коротко о главном

Тишина бота имеет одну из шести причин, и проверять их нужно по очереди: сервер, токен, вебхук, лимиты, права, зависимости. О поломке стоит узнавать раньше клиентов, для этого нужна проверка раз в несколько минут и канал, не зависящий от самого бота.

Бот уже молчит или нужен сторож? Напишите мне в Telegram слово «ДИАГНОСТИКА». Подробнее на странице Telegram и MAX боты.