Чому Twitch-бот пропускає повідомлення модераторів

Спочатку визначте, на якому етапі зникає повідомлення

Перевірте, чи отримує бот звичайні повідомлення в тому самому каналі. Якщо в логах немає ні глядачів, ні модераторів, проблема зазвичай в авторизації, підключенні до чату або назві каналу. Якщо глядачі видно, а репліки модератора відсутні, шукайте причину у фільтрі ролей, IRC-тегах або підписці EventSub.

Дивіться не лише на відповідь бота в чаті, а на журнал вхідних подій. Повідомлення може дійти до застосунку, але не запустити команду через префікс, кулдаун, стоп-слова, ігнор-лист або перевірку прав. Для тесту надішліть від глядача й модератора однакову коротку фразу, потім однакову команду.

Перевірте канал, акаунт бота й IRC-з'єднання

Переконайтеся, що бот увійшов саме в потрібний канал і під тим акаунтом, який має читати чат. Після перейменування каналу, зміни логіна або перемикання між тестовим і робочим середовищем застосунок може залишатися онлайн, але слухати інший чат.

У лозі підключення мають бути видно успішна авторизація, нік бота й команда входу в канал. Після обриву з'єднання перевірте не лише спроби перепідключення, а й факт нового успішного входу. Автоперепідключення без запису помилки приховує прострочений токен, неправильний пароль OAuth або помилку в назві каналу.

Перевірте OAuth-токен і права на читання

Токен має належати акаунту, через який бот читає чат. Не плутайте його з токеном стрімера: права власника каналу не передаються окремому акаунту бота. Для читання повідомлень через IRC потрібен scope chat:read.

Якщо повідомлення приймаються через EventSub, для події чату потрібен користувацький токен із правом user:read:chat. Залежно від схеми авторизації та того, хто створює підписку, також можуть знадобитися права для доступу бота до каналу, зокрема channel:bot. Не додавайте scope навмання: звіряйте їх із поточною схемою підписки й акаунтом, від імені якого вона створюється.

Перевірити дійсність користувацького токена й список наданих прав можна запитом:

curl -H "Authorization: OAuth $BOT_OAUTH_TOKEN" https://id.twitch.tv/oauth2/validate

У відповіді перевірте логін, ідентифікатор користувача, термін дії та масив scopes. Якщо chat:read або user:read:chat відсутній, потрібна повторна авторизація з потрібним набором прав. Недолік такого рішення в тому, що старі токени й збережені сесії потрібно замінити в конфігурації бота, інакше він продовжить працювати з попередніми правами.

Розділіть діагностику IRC і EventSub

IRC і EventSub доставляють повідомлення різними шляхами. IRC передає потік чату постійним з'єднанням: у сирому лозі потрібно знайти рядок PRIVMSG від модератора. EventSub передає подію channel.chat.message через створену API-підписку: тут перевіряють її статус, condition і транспорт доставки.

Якщо бот використовує обидва джерела, записуйте джерело кожної події в лог. Інакше одне повідомлення може обробитися двічі, а збій одного транспорту залишиться непомітним. Якщо використовується лише EventSub, відсутність IRC-підключення не вважається помилкою. Недолік схеми EventSub — при неправильній або вимкненій підписці бот не побачить повідомлення взагалі, навіть із робочим токеном.

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

У списку підписок знайдіть подію channel.chat.message. У запису має бути активний статус. У condition перевірте broadcaster_user_id — це ідентифікатор каналу стрімера — і user_id користувача, який отримує події. Помилка в будь-якому з цих ID часто виглядає як вибіркова відсутність повідомлень.

Запросіть список підписок через GET /helix/eventsub/subscriptions. У відповіді перевірте type, status, condition і transport. Статус enabled означає, що підписка активна; повідомлення про збій доставки, видалений запис або інший канал укажуть на причину. Для цього запиту використовуйте токен і Client ID того застосунку, який створював підписку.

Не орієнтуйтеся лише на наявність запису в панелі або базі даних бота. Підписка могла бути створена для тестового каналу, видалена після помилки доставки або стосуватися іншого застосунку. Недолік перевірки через API в тому, що вона показує конфігурацію підписки, але не пояснює логіку фільтрації всередині самого обробника.

Увімкніть IRC-теги й перевірте роль автора

Якщо перевірка прав будується на IRC, клієнт має запросити capability twitch.tv/tags. Без тегів бот може отримати текст і нік автора, але не побачити поля mod і badges. У такому разі звичайні команди приходять, а модераторські правила дають хибну відмову.

У сирому повідомленні модератора шукайте mod=1 і badges=moderator/1. Поле user-type може бути відсутнім, порожнім або не відповідати актуальній ролі, тому не використовуйте його як єдину ознаку. Парсер має коректно обробляти порожні значення тегів і екрановані символи; недолік IRC-підходу саме в необхідності розбирати цей формат самостійно.

Якщо mod=1 немає, спочатку переконайтеся, що capability для тегів справді підтверджена сервером, а не лише надіслана клієнтом. Потім перевірте badges. Значення moderator/1 означає модератора, broadcaster/1 — власника каналу. VIP зазвичай має badge vip/1, але VIP не стає модератором автоматично. Стрімера й VIP не варто вважати модераторами за ніком, кольором або display-name: роль визначайте за badges і окремими правилами доступу.

Перевірте правила ролей у коді й налаштуваннях

Порівняйте сирі події від глядача, VIP, модератора й власника каналу з однаковим текстом. Якщо подія від модератора дійшла до застосунку, але обробник її пропустив, помилка знаходиться після прийому: у перевірці ролі, чорному списку, антиспамі або маршрутизації команд.

• Приводьте логіни до одного регістру перед порівнянням.
• Перевіряйте mod=1 і badge moderator, а не один фіксований набір тегів.
• Окремо визначте права для broadcaster, moderator, vip і акаунта самого бота.
• Перевірте, чи не потрапив модератор до ігнор-листу, бан-листу або списку заборонених користувачів.
• Подивіться порядок умов: антиспам або стоп-слова можуть спрацювати раніше за перевірку ролі.
• Переконайтеся, що команда не блокується правилом для повідомлень зі згадкою, посиланням або повтором тексту.

Ручний список ніків підходить лише для короткої діагностики. Його недолік — він застаріває після зміни модераторів, перейменування акаунта або зміни ролей у каналі.

Виключіть формат команди, ліміти й прихований ігнор

Бот може бачити повідомлення й навмисно не відповідати. Перевірте кулдаун команди, ліміт повідомлень від одного користувача, захист від повторів, фільтр емодзі й стоп-слів. Модератори нерідко надсилають команди швидко й можуть потрапляти під антиспам нарівні з глядачами.

Окремо протестуйте звичайну фразу й команду з префіксом. Якщо фраза є в лозі, а команда не дійшла до результату обробки, перевірте префікс, розкладку, пробіли, невидимі символи й аргументи. Команди зі слешем і дії модерації не завжди приходять у вигляді звичайного тексту, який очікує обробник.

Записуйте причину рішення щодо кожного повідомлення

Для діагностики зберігайте час, джерело події, канал, ID автора, тип повідомлення, теги й підсумок обробки. Текст можна маскувати, якщо він не потрібен для пошуку помилки. У лозі має бути конкретна причина: повідомлення не отримано, не розпізнано роль, не пройшов префікс, спрацював кулдаун, користувач в ігнорі або вимкнена підписка EventSub.

Не записуйте у звичайні логи OAuth-токени, секрет застосунку, адреси вебхуків і повні заголовки авторизації. Ці дані зручні під час налагодження, але їхній витік може відкрити доступ до бота й налаштувань застосунку.

Чек-лист діагностики за порядком

1. Надішліть однакову фразу й однакову команду від глядача й модератора.
2. Перевірте сирий лог і визначте, чи прийшло повідомлення через IRC, EventSub або обидва джерела.
3. Якщо IRC не отримує повідомлення, звірте акаунт бота, назву каналу, токен і успішний вхід у чат.
4. Якщо IRC-повідомлення прийшло, переконайтеся, що ввімкнено теги, потім перевірте mod=1 і badges=moderator/1.
5. Якщо mod=1 відсутній, перевірте підтвердження twitch.tv/tags і розрізніть moderator/1, vip/1 і broadcaster/1.
6. Перевірте токен через validate: для IRC потрібен chat:read, для EventSub-повідомлень — user:read:chat.
7. Під час роботи через EventSub перевірте channel.chat.message, статус enabled, condition і transport у списку підписок.
8. Порівняйте обробку ролей, ігнор-лист, антиспам, префікс, кулдаун і стоп-слова.
9. Додайте в лог явну причину, з якої кожне повідомлення прийнято, проігноровано або відхилено.