Чому телеграм-бот не реагує на команди

Чому телеграм-бот не реагує на команди: швидка коротка відповідь

Токен і BotFather: чи валідний токен, задані команди та scope

Відкрийте BotFather і перевірте, що токен актуальний і ви не робили нещодавно /revoke (відклик токена). Звірте /setcommands і потрібний scope (область: за замовчуванням/для груп/для PM) з тим, що прописано в коді. Якщо команди не збігаються за назвою/локаллю, автодоповнення й тригери не спрацюють. У більшості інцидентів достатньо оновити список команд і підставити правильний токен.

Коли токен і команди підтверджені, перевірте воронку на невеликому трафіку. Акуратна накрутка телеграм малими партіями допоможе заміряти реакцію на команди, швидкість відповіді бота й конверсію в цільову дію. Подавайте рівномірно 30–60 хвилин і порівняйте метрики до та після.

Канал апдейтів: webhook дає 200 OK чи getUpdates повертає події

Визначте, звідки бот отримує події: webhook (вебхук) чи long polling (опитування), але не одночасно. Викличте getWebhookInfo і переконайтеся, що ваш URL відповідає 200 OK ≤ 10 секунд (без редиректів). Якщо є помилки — зніміть вебхук і тимчасово перевірте getUpdates — події мають приходити в консоль. Такий тест показує, чи проблема в мережі/сертифікаті, чи в логіці коду.

Права та контекст: Privacy Mode, права в групі, команда зі слешем/згадкою

У групах із увімкненим Privacy Mode бот бачить лише команди виду /cmd і згадки @MyBot (це нормально). Перевірте, що боту надано права писати/читати там, де він «мовчить» (особливо канали/супергрупи). Введіть команду зі слешем і згадкою: /cmd@MyBot — так виключите конфлікт імен. Без прав і коректного контексту реакції не буде, навіть якщо код правильний.

Бот не реагує на команди в Телеграм: покрокова діагностика

Перевірка токена і /setcommands (збігається з кодом і локаллю)

Порівняйте токен у змінних середовища з токеном у BotFather — чи не роз’їхались середовища dev/stage/prod. Оновіть /setcommands і перевірте локаль описів: українська/англійська версії мають відповідати клієнту користувача. Переконайтеся, що scope (область) правильний: за замовчуванням, для груп або для приватних чатів. Такий синк прибирає «німоту» без жодної правки сервера.

Webhook vs long polling — не одночасно, getWebhookInfo без помилок

Перевірте, що активний лише один канал отримання апдейтів — подвійний запуск дасть 409 Conflict. Перегляньте getWebhookInfo: чи не порожній last_error_message і чи приходить до вас POST із апдейтом. Якщо вебхук «висить», зніміть його (deleteWebhook?drop_pending_updates=true) і тимчасово ввімкніть polling. Так ви відокремите мережеві помилки від логічних.

Логи й винятки в хендлерах, ідемпотентність і offset

Увімкніть детальний лог: update_id, chat_id, handler, час початку/завершення та статус. Відловлюйте непіймані винятки: падіння одного обробника «з’їдає» реакцію на команду. Зберігайте last_update_id і дотримуйтеся ідемпотентності (без повторної обробки) — це прибирає дублікати й «пропуски». Після фіксу повторно запустіть тестову команду й перевірте ланцюжок у логах.

Чому бот не відповідає в групі

Privacy Mode увімкнено: потрібна форма /cmd@MyBot або reply

Коли Privacy Mode увімкнено, бот не бачить звичайні повідомлення й очікує команду з явним зверненням. Використовуйте форму /cmd@MyBot або відповідь на його повідомлення (reply), щоб передати контекст. Якщо потрібно читати звичайні фрази — вимкніть /setprivacy у BotFather. Це безпечніше, ніж шукати «баг» у коді там, де все працює за правилами платформи.

Немає прав/не адміністратор: бот не бачить повідомлення/не може писати

У групах і каналах права різні, і без ролі адміністратора публікація може бути заборонена. Перевірте прапорці: надсилання повідомлень, посилань/медіа, закріплення/видалення повідомлень. Після зміни прав перезапустіть бота, щоб кеш чатів оновився. Відсутність прав — часта й найшвидша у виправленні причина «тиші».

Обмеження групи/супергрупи, фільтри й slow mode

Супергрупи мають антифлуд і «повільний режим» — візуально бот «мовчить» довше. Перевірте фільтри, обмеження частоти й права на посилання/медіа. Спробуйте ту саму команду в тестовій групі без обмежень, щоб виключити зовнішні фактори. Якщо в «пісочниці» все працює — коригуйте політику групи.

Чому бот не відповідає в особистих повідомленнях

Користувач заблокував бота (403) або не писав першим

Код 403 у sendMessage зазвичай означає, що користувач заблокував бота або ніколи не писав йому першим. Попросіть почати діалог вручну (перше повідомлення) — це зніме заборону PM. Не ретрайте одне й те саме повідомлення — це виглядає як спам і витрачає ліміти. Логуйте такі випадки, щоб не намагатися писати в закриті особисті повідомлення знову.

Rate limit 429 і антиспам-івенти

Якщо бот часто відповідає поспіль, ви ризикуєте отримати 429 Too Many Requests. Увімкніть бекофф (паузи між повторами) і черги, зменшіть частоту. Позначте «вікна тиші» для масових розсилань, щоб не впертися в ліміти. Так ви збережете доставку й довіру.

Непідтримуваний тип апдейта: callback_query, edited_message

Іноді команда «захована» у callback або зміненому повідомленні (edited_message), а обробника немає. Перевірте, що хендлери підписані на всі використовувані типи апдейтів: message, command, callback_query. Додайте заглушки й лог на неочікувані типи — бот перестане «падати мовчки». Це швидкий спосіб побачити справжню форму події.

Webhook не працює: TLS, DNS, 200 OK

Сертифікат/ланцюг/SNI, термін дії

Переконайтеся, що сертифікат виданий публічним CA, ланцюг повний (є проміжний сертифікат), CN відповідає домену, SNI увімкнено. Прострочений або неповний сертифікат Telegram не прийме — вебхук «онлайн», але апдейти не надходять. Перевірте дати та issuer і перезапустіть сервер після оновлення. Це 5 хвилин роботи й море зекономленого часу.

Відповідь < 10 с, без редиректів, коректний Content-Type

Ваш обробник повинен повертати 200 OK швидко (краще до 2 секунд, максимум 10) і без редиректів. Content-Type має відповідати відповіді, інакше Telegram видає «wrong response». Довгі операції винесіть у фон або чергу, щоб не блокувати відповідь. Так ви уникнете таймаутів і повторів.

409 Conflict через одночасний polling — як зняти deleteWebhook

Якщо бачите 409, значить одночасно активні webhook і polling. Зніміть вебхук: deleteWebhook?drop_pending_updates=true — і переконайтеся, що polling єдиний. Після виправлення поверніть setWebhook і перевірте getWebhookInfo — помилки мають зникнути. Тримайте один канал апдейтів у кожен момент часу.

Long polling не надходить

offset/timeout, дублікати апдейтів і пропуски

Зберігайте last_update_id і зсувайте offset на +1, щоб не отримувати дублікати. Ставте timeout 25–30 секунд і перевіряйте, що апдейти йдуть без «дір». Якщо бачите пропуски — перевірте чергу, обробники й місце фіксації offset. Це база стабільної доставки.

Єдина точка прийому, без паралельних воркерів

Лише один процес повинен читати getUpdates, інакше отримаєте «гонки» та дублікати. Окремі воркери можуть обробляти, але не приймати апдейти. Зробіть явну «єдину точку входу» та ідемпотентність при обробці. Так ви виключите «хаос» на вході.

Мережеві таймаути, проксі, NAT

Перевірте таймаути HTTP-клієнта та проксі, додайте бекофф і ретраї для тимчасових збоїв. На NAT/фаєрволі переконайтеся, що вихідні з’єднання до api.telegram.org дозволені. Якщо мережа «рветься», перейдіть на вебхук і відстежуйте час відповіді. Мережа — часта причина «тиші» поза кодом.

Ліміти й формати Bot API

400/401/403/409/413/429 — що означають і як виправити

400 Bad Request — помилка в параметрах/JSON: перевірте типи й поля. 401 Unauthorized — токен невірний/відкликаний: отримайте новий у BotFather і оновіть конфіги. 403 Forbidden — немає прав/користувач заблокував: запросіть права або попросіть користувача написати першим. 409 Conflict — запущено webhook і polling одночасно: зніміть webhook. 413 — занадто великий файл: стискайте/діліть. 429 — перевищено ліміт: вмикайте черги й бекофф.

Обмеження callback_data/inline, розміри файлів

Тримайте callback_data короткими, не кладіть туди великі JSON — зберігайте стан на сервері. Перевіряйте ліміти розмірів файлів для фото, відео, документів і аудіо. Слідкуйте за довжиною підписів і текстів, щоб не ловити «тихі» 400. Ці дрібниці регулярно «роняють» бота без явних помилок у коді.

Валідність JSON і кодувань

Ставте Content-Type: application/json і валідовуйте серіалізацію. Екрануйте спецсимволи й ураховуйте Unicode/емодзі. Тестуйте крайні випадки (довгі підписи, RTL-текст), щоб не падати в проді. Це проста страховка від нічних інцидентів.

Таблиця — Симптом → Причина → Що перевірити (вставити тут, 8–10 рядків)

Приклади рядків

Нижче — короткі підказки, які закривають найчастіші кейси. Тримайте їх під рукою як карту навігації перед дебагом. Спочатку виключіть 409/401/403 і проблеми TLS — це «критично». Решта йде другим кроком.

Симптом Причина Перевірка/виправлення Команда не підсвічується Немає /setcommands або не той scope BotFather /setcommands, локаль, збіг із кодом Мовчить у групі Privacy Mode/немає прав /setprivacy, права адміна, /cmd@MyBot Webhook «висить» TLS/не 200 OK getWebhookInfo, логи сервера, виправити сертифікат/відповідь Подвійні апдейти offset не рухається/два воркери Зберігати last_update_id, єдиний приймач 409 Conflict Webhook + polling одночасно deleteWebhook?drop_pending_updates=true 429 Too Many Requests Перевищено ліміт Бекофф/черги, знизити частоту

Міні-приклади команд для перевірки

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

Перед командами переконайтеся, що підставили справжній і ваш HTTPS-домен. У відповідях дивіться 200 OK і текст last_error_message у getWebhookInfo. Помилки TLS/timeout підкажуть напрямок виправлення. Після правки повторіть перевірку.

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

Тест polling

Для швидкої локальної перевірки подій використовуйте getUpdates з timeout. Якщо бачите апдейти тут, а вебхук мовчить — винні мережа/TLS/обробник. Це добрий спосіб локалізувати проблему за кілька хвилин. Не тримайте polling і webhook одночасно.

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

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

Перед релізом: токен, команди, privacy, права; webhook 200 OK; ліміти/моніторинг

Перевірте токен і /setcommands, переконайтеся в коректній локалі та scope. Перевірте права в чатах і режим Privacy Mode відповідно до сценарію. Переконайтеся, що вебхук дає 200 OK і ланцюг TLS повний; увімкніть моніторинг і алерти. Зафіксуйте порядок дій для перемикання каналів (runbook) і перевірте його на тестовому середовищі.

Під час інциденту: зафіксувати канал апдейтів, увімкнути розширені логи, тимчасово перейти на polling

Запишіть, який канал зараз активний, і вимкніть другий, щоб не отримати 409. Увімкніть розширений лог апдейтів і помилок та позначте час початку проблеми. Тимчасово перейдіть на polling, щоб не втрачати події, і паралельно виправляйте мережу/сертифікат/код. Після фіксу поверніться на вебхук і переконайтеся, що last_error_message порожній.

FAQ — коротко

Чому бот не реагує на команди лише в групі

Найчастіше увімкнено Privacy Mode або боту не вистачає прав писати/читати. Використовуйте форму /cmd@MyBot або вимкніть приватний режим, якщо потрібно читати звичайні повідомлення. Дайте права адміністратора й повторіть тест. Якщо в тестовій групі все працює — проблема в налаштуваннях цільової групи.

Що робити при 409/429/400 помилках Bot API

409 — вимкніть один канал апдейтів; 429 — увімкніть черги й бекофф; 400 — перевірте JSON і довжини полів. Для 401 оновіть токен, для 403 перевірте права/блок у PM. Зніміть getWebhookInfo і логи — вони підкажуть напрямок. Рухайтеся за чек-листом зверху вниз.

Як зрозуміти, проблема в сертифікаті чи в коді

Якщо getWebhookInfo показує TLS/timeout — виправляйте сертифікати й швидкість відповіді. Якщо polling отримує апдейти, а вебхук — ні, винні мережа/TLS/обробник. Перевірте SNI/CN, повний chain і час до 200 OK. Якщо й це в нормі — дивіться логи хендлерів.

Чи можна тримати і webhook, і polling одночасно

Ні, для одного бота допускається лише один спосіб прийому апдейтів. Одночасний запуск призводить до 409 Conflict і дублювання подій. Тримайте «єдину точку входу» й фіксуйте порядок перемикань у runbook. Так ви уникнете «гонок» і дивних багів.