Почему 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. Добавьте в лог явную причину, по которой каждое сообщение принято, проигнорировано или отклонено.