Чому бот не працює в Телеграм

Бот перестав працювати в телеграм? Я покажу, що критично перевірити одразу (токен, вебхук, TLS) і що важливо. Коли токен, вебхук і TLS уже справні, перевірте воронку на реальних користувачах малими хвилями трафіку: Накрутка підписників телеграм дасть швидкий контрольний приплив для заміру welcome-повідомлень, відгуку бота та утримання. Фіксуйте p95 відповіді, error rate і конверсію в цільову дію до та після запуску.

Праймер: офіційні посилання та стандарти

Офіційні джерела (швидкі посилання)

Потрібні першоджерела, щоб довіряти кожному кроку? Звіряйтеся з документацією Telegram Bot API: setWebhook/getUpdates/ліміти – https://core.telegram.org/bots/api. Вимоги до HTTPS і сертифікатів (публічний CA, повний chain, SNI/CN) – https://core.telegram.org/bots/webhooks#https-certificate. Про Privacy Mode у BotFather – https://core.telegram.org/bots/features#privacy-mode.

Міні-матриця критичності (triage за 30 секунд)

Спочатку закриваємо Критично: токен/дублікати, 409 (подвійний канал апдейтів), TLS chain/CN/SNI, швидкий 200 OK. Потім Важливо: IPv6/AAAA і DNS, ліміти 429 (часті запити), права/Privacy Mode. Опціонально: вікна тиші в cron, circuit breaker (автовимикач запитів) і тонкі налаштування черг. Така розмітка економить час і знижує MTTR.

Швидка коротка відповідь (що перевірити за 2 хвилини)

Токен і права бота (BotFather, admin/Privacy Mode)

Токен не змінювали вчора і він не відкликаний (/revoke у BotFather)? Бота додано адміністратором там, де він має писати (група/канал), і йому надані потрібні права? Увімкнено Privacy Mode і чи не заважає він читанню звичайних повідомлень у групах (при ввімкненні бот бачить лише команди)? У моїй практиці 3 з 10 інцидентів закриваються вже на цьому кроці.

Канал апдейтів (webhook встановлено? 200 OK? чи запустити long polling)

Як бот отримує події зараз – webhook чи long polling (опитування)? Якщо webhook, викличте getWebhookInfo і переконайтеся, що ваш URL стабільно повертає 200 OK за 1–2 секунди. Для налагодження тимчасово зніміть webhook і увімкніть polling (не одночасно, інакше буде 409 Conflict). Такий перемикач одразу показує: у нас проблема з мережею/сертифікатом чи логікою коду.

Мережа/сертифікати (TLS валідний? DNS/IPv4/IPv6? фаєрвол)

Відкривається ваш домен через HTTPS без попереджень? Перевірте ланцюг сертифіката і SNI (ім’я сервера в TLS), а також CN (ім’я домену в сертифікаті) – помилки тут «глушать» вебхук. Перегляньте DNS і маршрути: чи немає розсинхрону IPv4/IPv6 і чи не блокує фаєрвол вхідні/вихідні запити. Часто це найшвидший спосіб виправлення без змін у коді.

Decision tree: покрокова діагностика інциденту

Крок 1 – Токен: валідний? не відкликаний? (BotFather → /revoke, /token)

Порівняйте токен у змінних середовища з токеном у BotFather – чи не роз’їхалися dev/stage/prod. Якщо робили /revoke або отримали новий /token, старий ключ одразу мертвий – оновіть секрети в CI/CD і перезапустіть воркери. Перевірте дублікати середовищ, де міг залишитися старий ключ. У моїй практиці саме розсинхрон токенів валив бота на години.

Крок 2 – Канал апдейтів: webhook чи long polling (не одночасно)

Активний лише один канал доставки подій? 409 Conflict в API майже завжди означає, що запущені обидва. Для локальної перевірки зніміть webhook (deleteWebhook з drop_pending_updates) і увімкніть getUpdates. Так ви виключите мережу й побачите обробник апдейтів напряму.

Крок 3 – Webhook: getWebhookInfo → є last_error_date/last_error_message?

Викличте getWebhookInfo і прочитайте last_error_message: timeout, TLS error, wrong response? Timeout – обробник відповідає надто довго; TLS error – проблема із сертифікатом/ланцюгом; wrong response – не 200 OK або не той формат відповіді. Логуйте вхідний payload (тіло запиту) і час відповіді – це економить години.

Крок 4 – TLS: публічний сертифікат, ланцюг, SNI, 200 OK ≤ 10 c

Використовуйте публічний CA і віддавайте повний chain (проміжні сертифікати). Переконайтеся, що SNI (ім’я сервера) і CN (домен у сертифікаті) збігаються з URL вебхука. Повернення 200 OK має бути швидким: краще до 2 секунд, максимум до 10 секунд. У реальних інцидентах неповний ланцюг був найчастішою причиною «тиші».

Крок 5 – Ліміти/формати: 429, занадто великі файли, невірні payload

Перевірте логи на 429 Too Many Requests і ввімкніть бекофф (повторні спроби за експонентою). Звірте розміри файлів і довжини полів (особливо callback_data) з лімітами Bot API. Валідовуйте JSON і типи апдейтів, щоб несподівані події не «роняли» обробник. Ідемпотентність (без повторної обробки) рятує від дублів під час ретраїв.

Крок 6 – Права в чаті: бот не адмін/Privacy Mode блокує читання

Чи вистачає боту прав на надсилання повідомлень, посилань і медіа там, де він «мовчить»? У групах із увімкненим Privacy Mode бот бачить лише команди й інлайн – це не баг. У каналах писати можна тільки з правами адміністратора. Ми заздалегідь описуємо вимоги до прав, щоб їх не загубили під час міграції.

Крок 7 – Код і логи: непіймані винятки, зависання, ретраї

Увімкніть детальний лог: вхідний апдейт, ID чату, час обробки, статус відповіді. Відловіть непіймані винятки й перевірте черги повідомлень – чи немає «залипань». Винесіть зовнішні виклики у фон, поставте таймаути (час очікування відповіді) і circuit breaker (автовимикач запитів). Це стабілізує 200 OK і зменшує зависання.

Крок 8 – Мережа/хостинг: фаєрвол, NAT, проксі, контейнерні healthchecks

Перевірте, чи не блокує проксі/фаєрвол вхідні й вихідні запити. Переконайтеся, що health-checks (URL перевірки стану сервісу) не «вбивають» воркер під навантаженням. Чи немає проблем із DNS/TTL під час переїзду домену і чи не заважає AAAA-запис для IPv6. Моніторинг затримок і аптайму дасть ранній сигнал деградації.

Токен і BotFather (налаштування, які найчастіше ламають)

Невірний/відкликаний токен, дублікати середовищ

Зберігайте токен у секрет-менеджері й поширюйте через єдине джерело правди. Після /revoke оновлюйте всі середовища, інакше частина воркерів залишиться з «мертвим» ключем. Перевірте, чи не запущені старі контейнери зі старими змінними середовища. Це класика, яка ламає прод просто посеред робочого дня.

Команди й меню: неправильні слеші, описи, локалі

Перевірте /setcommands і локалізовані описи – перший рядок видно одразу в клієнті. Дотримуйтеся формату: слеш, команда, короткий опис без «води» й зайвих символів. Для кількох мов тримайте окремі набори, щоб клієнт підхоплював локаль користувача. Ми завантажуємо команди з JSON під час релізу, щоб не правити вручну.

Privacy Mode і робота в групах/каналах

Вирішіть заздалегідь: бот читає все чи лише команди? Якщо потрібно читати звичайні повідомлення – вимкніть Privacy Mode (і додайте фільтри по чатах). Для публікації в каналі надайте права адміністратора й позначте потрібні прапорці. Так не доведеться «чекати дива» від приватного бота.

Webhook: коректна реєстрація та прийом апдейтів

setWebhook: валідний HTTPS-URL, один бот → один webhook

Реєструйте вебхук на доступному ззовні HTTPS-домені. Дотримуйтеся правила «один бот – один вебхук», без дублікатів і старих хвостів. Перед перемиканням робіть drop_pending_updates, щоб не тягнути старі апдейти. Ми завжди перевіряємо health-endpoint перед увімкненням реального трафіку.

Сертифікат: публічний CA, повний ланцюг, SNI, актуальний CN

Слідкуйте за терміном дії та цілісністю ланцюга, збігом CN/домена і коректністю SNI. На мультисайтових серверах перевірте віртуальні хости й роутинг. Неправильний SNI/CN виглядає як «мовчання» без явної помилки в логах. Це виправляється за хвилини, якщо знати, куди дивитися.

Відповідь сервера: 200 OK швидко; таймаути, ретраї, ідемпотентність

Повертайте 200 OK одразу, важкі операції переносіть у фонові черги. Ставте ретраї (повторні спроби) й ідемпотентність (без повторної обробки) на чутливих ділянках. Логуйте час відповіді та ID апдейта, щоб відстежувати стрибки. У моїй практиці винесення зовнішніх викликів у фон миттєво зняло «таймаути».

Long polling як альтернатива (для локального налагодження)

getUpdates: offset/timeout, подвійні апдейти

Тримайте timeout 25–30 секунд і зсувайте offset, щоб не ловити дублікати. Зберігайте last_update_id і застосовуйте ідемпотентність (без повторної обробки). Не блокуйте отримання апдейтів важкими завданнями. Polling – швидкий спосіб ізолювати проблему від мережі/TLS.

Паралелізм, черги, блокувальні операції

Делегуйте довгі операції воркерам і чергам, а не тримайте їх у обробнику. Контролюйте кількість паралельних воркерів і ліміти Bot API, щоб не ловити 429. Додайте метрики черг і активних обробників у моніторинг. Це робить поведінку бота передбачуваною під навантаженням.

Перехід webhook ↔ polling без «гонок»

Знімайте вебхук з drop_pending_updates перед запуском polling – і навпаки. Фіксуйте кроки в журналі релізу, щоб не отримати 409 Conflict. Тримайте лише один канал апдейтів у кожен момент часу. Так ви уникнете подвійної доставки та дивних багів.

Ліміти й формати Bot API (перенесено ближче до початку)

Обмеження: розмір файлів, частота запитів, 429

Звірте ліміти за розміром файлів і частотою запитів у документації Bot API. Увімкніть бекофф і черги для масових відправлень, щоб не ловити 429 Too Many Requests. Дотримуйтеся лімітів на чат і на бота, інакше повідомлення будуть «відскакувати». Ми ставимо алерти на наближення до порогів, щоб реагувати заздалегідь.

Обмеження інлайн/кнопок: callback_data, довжини полів

Не кладіть великі JSON у callback_data – зберігайте стан на сервері. Валідовуйте довжину полів, шифруйте або кодуйте маркери компактно. Екрануйте користувацьке введення, щоб не «ламати» Markdown/HTML. Прості маркери + серверний стан = надійність і швидкість.

Контент-типи та кодування JSON

Надсилайте коректний Content-Type і валідний JSON на вході/виході. Враховуйте Unicode, емодзі, RTL-текст і довгі підписи. Автотести на серіалізацію заощаджують години в проді. Ми тримаємо заглушки на рідкісні події, щоб бот не падав мовчки.

Права й доступи в чатах

Боту не вистачає прав: читання/видалення/запрошення/публікація

Перевірте прапорці прав на надсилання повідомлень, посилань, медіа та керування повідомленнями. У каналі без адмінки бот писати не буде – так це працює. Для закріплень і посилань потрібні окремі дозволи – уточніть це заздалегідь. Ми завжди описуємо потрібні права в README проєкту.

Обмеження групи, «мовчить» у супергрупах

Супергрупи мають антифлуд і slow-mode – візуально бот «мовчить». Перевірте фільтри та режим «тільки адміністратори», а також Privacy Mode. Якщо потрібен доступ до звичайних повідомлень – вимикайте Privacy Mode або працюйте командами. Тест у пісочниці економить багато нервів.

Користувач заблокував бота; заборони на PM

403 Forbidden у особистих повідомленнях = користувач заблокував бота. Не надсилайте повторно й не витрачайте ліміти – поважайте вибір користувача. Додайте інструкцію з розблокування в FAQ і інтерфейсі. Це зменшує скарги й підвищує довіру до бота.

Мережа та інфраструктура

Фаєрвол/NAT/проксі/CDN: проброс портів і білі списки IP

Відкрийте вихідні на api.telegram.org:443 і вхідні на порт вебхука. За NAT/проксі перевірте заголовки X-Forwarded і реальний IP клієнта. За потреби додайте IP Telegram у білі списки хостингу. Ми регулярно робимо трасування й перевіряємо MTU при нестабільній мережі.

DNS, IPv4/IPv6 невідповідності, перенесення домену

Перевірте A/AAAA записи й TTL, особливо після перенесення домену. Несумісність IPv6 спричиняє таймаути на частині клієнтів – вимкніть AAAA або налаштуйте підтримку. Дочекайтеся поширення DNS перед перемиканням вебхука. Ці дрібниці часто пояснюють «містичні» збої.

Хостинг/серверлесс таймаути, холодний старт, обмеження пам’яті/CPU

Звірте таймаути функцій і ліміти пам’яті/CPU – при недовантаженні все «висить». Холодний старт ламає 200 OK – тримайте «теплий» пул або пінг за розкладом. Слідкуйте за p95 затримкою й часом до відповіді: це ранні індикатори проблем. У нашому досвіді це виявляє деградацію раніше, ніж її помічають користувачі.

Логіка й код бота

Непіймані винятки, падіння воркера, черги повідомлень

Увімкніть глобальне перехоплення помилок і алерти на падіння процесів. Слідкуйте за довжиною черг і підтверджуйте повідомлення (ack), щоб не створювати дублікати. Перевіряйте витоки пам’яті, щоб воркери не «вмирали» тихо. Watchdog-перезапуск часто повертає доступність без редеплою.

Невідповідність схемі апдейтів: необроблені типи (poll, shipping, chat_join_request)

Звірте список типів апдейтів і додайте заглушки на рідкі події. Логуйте неочікувані payload (тіло запиту), щоб швидко бачити причину падіння. Розширте тести: poll, shipping_query, pre_checkout_query, chat_join_request. Так ви не отримаєте сюрприз у проді.

Локалі/таймзона, години бездіяльності, конфлікт cron-завдань

Перевірте таймзону сервера та розклад cron – чи не заважають вони обробці апдейтів. Додайте вікна тиші для нічних годин, якщо користувачам краще не писати. Розведіть cron і воркери по чергах, щоб не блокували один одного. Це прибирає «містичні» провали залучення.

Інтеграції та зовнішні API

Ключі, квоти, SLA сторонніх сервісів

Зберігайте ключі в секрет-сховищі та перевіряйте квоти заздалегідь. Слідкуйте за SLA партнерів і готуйте «план Б» на випадок недоступності. Тримайте посилання на статус-сторінки постачальників. Ми додаємо кеш і fallback-и, щоб бот не залежав від чужих збоїв.

Таймаути, експоненційні ретраї, circuit-breaker-и

Ставте таймаути (час очікування відповіді) й ретраї (повторні спроби) на зовнішніх викликах. Вмикайте circuit breaker (автовимикач запитів), щоб не перевантажувати сервіси. Повідомляйте користувачу дружні тексти під час деградації. Це зберігає довіру й ліміти.

Валідація зовнішніх даних і санітизація

Санітизуйте Markdown/HTML і екрануйте спецсимволи. Валідовуйте довжини/типи, навіть якщо «за документацією все ок». Не довіряйте зовнішнім JSON і перевіряйте поля на вході. Такий захисний шар позбавляє від неочікуваних збоїв.

Таблиця 1 – Коди/ситуації Bot API → що означає → як виправити

(Вставити компактну таблицю до 10 рядків)

Таблиця 2 – Симптом → ймовірна причина → що перевірити

(Вставити компактну таблицю до 10 рядків)

Приклади команд і перевірок (для копіпасту)

Перевірити/поставити webhook

curl -F "url=https://example.com/bot-hook" https://api.telegram.org/bot<TOKEN>/setWebhook curl https://api.telegram.org/bot<TOKEN>/getWebhookInfo

Зняти webhook і перейти на polling

curl "https://api.telegram.org/bot<TOKEN>/deleteWebhook?drop_pending_updates=true" curl "https://api.telegram.org/bot<TOKEN>/getUpdates?timeout=30"

Швидкий healthcheck обробника

curl -i https://example.com/bot-hook/health

Чекліст перед релізом і під час інциденту

Перед релізом

Токен, команди, Privacy Mode, права в чатах. Вебхук: валідний сертифікат, 200 OK, таймаути (час очікування відповіді). Ліміти, черги, моніторинг помилок і затримок. Задокументуйте версії, домени та режим отримання апдейтів.

Під час інциденту

Зупиніть шторм запитів і увімкніть бекофф. Увімкніть розширений лог апдейтів і помилок із позначкою часу. Перевірте інфраструктуру (DNS, TLS, мережу), за потреби зробіть відкат/канарковий реліз. Тимчасово перейдіть на polling до виправлення вебхука.

Логи, алерти та SLO

Лог-шаблон (копіпаста)

Єдиний формат логів прискорює пошук причин і порівняння релізів. Рекомендуємо поля: request_id, update_id, chat_id, handler, t_start, t_finish, duration_ms, status_code, error_class, error_message, retry_count, webhook_url. Тримайте правило: p95 duration_ms ≤ 3000 (95% запитів швидше 3 с). Це проста мета, що добре корелює з «бот відповідає вчасно».

{ "request_id":"...", "update_id":123456789, "chat_id":-100123456, "handler":"onCallback", "t_start":"2025-11-14T09:00:00Z", "t_finish":"2025-11-14T09:00:01Z", "duration_ms":980, "status_code":200, "error_class":null, "error_message":null, "retry_count":0, "webhook_url":"https://example.com/bot-hook" }

Алерти та SLO

Поставте алерт, якщо last_error_date у getWebhookInfo оновився за останні 5 хвилин – це ранній сигнал. Алерт на p95 duration_ms > 2000 ms 5 хвилин поспіль – привід розбирати затримки. SLO: ≥ 99.9% успішних 200 OK вебхука і p95 < 2 s. Ці цілі реалістичні та дають передбачувану якість сервісу.

Перевірка TLS за хвилину

Chain-test команда

Швидко перевірити ланцюг сертифікатів можна однією командою OpenSSL. Виконайте команду нижче й перегляньте issuer/subject/dates, а також що ланцюг повний (є intermediate). Зверніть увагу на CN/SAN (ім’я домену) та актуальні дати – прострочений сертифікат «глушить» вебхук. Якщо chain неповний – налаштуйте вебсервер на віддачу повного набору.

echo | openssl s_client -servername example.com -connect example.com:443 -showcerts 2>/dev/null | openssl x509 -noout -issuer -subject -dates

Покращення в глибину (ідеально на найближчий спринт)

Автотести сумісності вхідних апдейтів

Покрийте рідкі типи подій: poll, shipping_query, pre_checkout_query, chat_join_request. Мета проста: бот не падає на неочікуваних payload (тілах запитів). Додайте заглушки та валідатори схем, щоб ловити невідповідності. Такий шар запобігає «тихим» падінням після оновлень клієнтів.

Ідемпотентність на рівні сховища

Створіть таблицю processed_updates(update_id PK, processed_at) або Redis-ключі з TTL. Патерн «check-then-set» гарантує захист від дублікатів під час ретраїв (повторних спроб). Обробка має бути атомарною: записали – отже оброблено. Це прибирає «привидів» і неочікувані повторні платежі чи дії.

Уніфікація ретраїв і circuit breaker’ів

Винесіть у middleware: timeout, експоненційний backoff із jitter, max retries, коротке замикання при 5xx/timeout. Єдина політика робить поведінку передбачуваною й економить ліміти. Додайте дружні повідомлення користувачу при деградації. Це підвищує довіру й утримання.

Дашборд: мінімум графіків

Що моніторити обов’язково

Потоки вебхука: кількість запитів, частка 200/не-200, p95/avg затримка. Розподіл типів апдейтів: бачити, що реально приходить і де прогалини. Помилки за кодами: 400/401/403/409/429/5xx – зрозуміла карта несправностей. Черги/розсилання: глибина, швидкість обробки, відхилення від норми.

Runbook інциденту (1 сторінка)

Сценарій: «бот мовчить у групах»

Перевірте Privacy Mode і права: бот бачить лише команди? Увімкніть/вимкніть за сценарієм. Зробіть getWebhookInfo, перегляньте last_error_message: чи немає TLS/timeout. Перевірте TLS chain/CN/SNI і тимчасово перейдіть на polling, потім – відкат/канарковий реліз. Така послідовність скорочує MTTR і усуває «гонки» каналів.

Рідкі кейси: перевірте, якщо все інше гаразд

Що ще трапляється у проді

Проксі/балансувальник перезаписує заголовок Host – SNI/маршрут ламається; явно форсуйте proxy_set_header Host ... і коректний SNI на бекенді. Serverless страждає від холодного старту (>3–5 с): тримайте прогрів за cron. Інлайн-режим: перевірте ліміти answerInlineQuery і кеш. MarkdownV2: екрануйте спецсимволи _[]()~ – інакше будуть «тихі» 400.