Pourquoi le bot Twitch ignore les messages des modérateurs

Déterminez d'abord à quelle étape le message disparaît

Vérifiez si le bot reçoit les messages ordinaires dans le même canal. Si les logs ne contiennent ni spectateurs ni modérateurs, le problème vient généralement de l'autorisation, de la connexion au chat ou du nom du canal. Si les spectateurs sont visibles mais que les répliques du modérateur sont absentes, cherchez la cause dans le filtre de rôles, les balises IRC ou l'abonnement EventSub.

Ne regardez pas seulement la réponse du bot dans le chat, mais le journal des événements entrants. Le message peut atteindre l'application sans déclencher la commande à cause d'un préfixe, d'un cooldown, de mots interdits, d'une liste d'ignorés ou d'une vérification des droits. Pour tester, envoyez une même courte phrase depuis un spectateur et un modérateur, puis une même commande.

Vérifiez le canal, le compte du bot et la connexion IRC

Assurez-vous que le bot a rejoint le bon canal et sous le compte qui doit lire le chat. Après un renommage du canal, un changement de login ou un basculement entre environnement de test et de production, l'application peut rester en ligne tout en écoutant un autre chat.

Dans le log de connexion doivent apparaître une autorisation réussie, le pseudo du bot et la commande de connexion au canal. Après une coupure, vérifiez non seulement les tentatives de reconnexion, mais aussi le fait d'une nouvelle connexion réussie. Une reconnexion automatique sans journalisation d'erreur masque un jeton expiré, un mot de passe OAuth incorrect ou une erreur dans le nom du canal.

Vérifiez le jeton OAuth et les droits de lecture

Le jeton doit appartenir au compte par lequel le bot lit le chat. Ne le confondez pas avec le jeton du streamer : les droits du propriétaire du canal ne sont pas transférés à un compte bot distinct. Pour lire les messages via IRC, le scope chat:read est nécessaire.

Si les messages sont reçus via EventSub, l'événement de chat nécessite un jeton utilisateur avec le droit user:read:chat. Selon le schéma d'autorisation et celui qui crée l'abonnement, des droits d'accès du bot au canal peuvent aussi être requis, notamment channel:bot. N'ajoutez pas de scopes au hasard : vérifiez-les par rapport au schéma d'abonnement actuel et au compte au nom duquel il est créé.

Pour vérifier la validité du jeton utilisateur et la liste des droits accordés, utilisez la requête :

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

Dans la réponse, vérifiez le login, l'identifiant utilisateur, la durée de validité et le tableau scopes. Si chat:read ou user:read:chat est absent, une nouvelle autorisation avec l'ensemble de droits requis sera nécessaire. L'inconvénient de cette solution est qu'il faut remplacer les anciens jetons et sessions enregistrées dans la configuration du bot, sinon il continuera de fonctionner avec les anciens droits.

Séparez le diagnostic IRC et EventSub

IRC et EventSub livrent les messages par des chemins différents. IRC transmet le flux du chat via une connexion persistante : dans le log brut, il faut trouver la ligne PRIVMSG du modérateur. EventSub transmet l'événement channel.chat.message via un abonnement API créé : ici, on vérifie son statut, sa condition et le transport de livraison.

Si le bot utilise les deux sources, enregistrez la source de chaque événement dans le log. Sinon, un message peut être traité deux fois, et une défaillance d'un transport restera invisible. Si seul EventSub est utilisé, l'absence de connexion IRC n'est pas une erreur. L'inconvénient du schéma EventSub est qu'avec un abonnement incorrect ou désactivé, le bot ne verra aucun message, même avec un jeton valide.

Vérifiez l'abonnement EventSub aux messages du chat

Dans la liste des abonnements, trouvez l'événement channel.chat.message. L'entrée doit avoir un statut actif. Dans la condition, vérifiez broadcaster_user_id — l'identifiant du canal du streamer — et user_id de l'utilisateur qui reçoit les événements. Une erreur dans l'un de ces ID ressemble souvent à une absence sélective de messages.

Demandez la liste des abonnements via GET /helix/eventsub/subscriptions. Dans la réponse, vérifiez type, status, condition et transport. Le statut enabled signifie que l'abonnement est actif ; une notification d'échec de livraison, une entrée supprimée ou un autre canal indiqueront la cause. Pour cette requête, utilisez le jeton et le Client ID de l'application qui a créé l'abonnement.

Ne vous fiez pas uniquement à la présence d'une entrée dans le panneau ou la base de données du bot. L'abonnement a pu être créé pour un canal de test, supprimé après une erreur de livraison ou appartenir à une autre application. L'inconvénient de la vérification via l'API est qu'elle montre la configuration de l'abonnement, mais n'explique pas la logique de filtrage au sein du gestionnaire lui-même.

Activez les balises IRC et vérifiez le rôle de l'auteur

Si la vérification des droits repose sur IRC, le client doit demander la capability twitch.tv/tags. Sans les balises, le bot peut recevoir le texte et le pseudo de l'auteur, mais ne pas voir les champs mod et badges. Dans ce cas, les commandes ordinaires passent, mais les règles de modérateur donnent un faux refus.

Dans le message brut du modérateur, cherchez mod=1 et badges=moderator/1. Le champ user-type peut être absent, vide ou ne pas correspondre au rôle actuel ; ne l'utilisez donc pas comme seul indicateur. Le parseur doit gérer correctement les valeurs vides des balises et les caractères échappés ; l'inconvénient de l'approche IRC réside précisément dans la nécessité de parser ce format soi-même.

Si mod=1 est absent, assurez-vous d'abord que la capability pour les balises a bien été confirmée par le serveur, et pas seulement envoyée par le client. Vérifiez ensuite badges. La valeur moderator/1 désigne un modérateur, broadcaster/1 — le propriétaire du canal. Un VIP a généralement la badge vip/1, mais un VIP ne devient pas modérateur automatiquement. Il ne faut pas considérer le streamer et le VIP comme modérateurs d'après le pseudo, la couleur ou le display-name : déterminez le rôle par les badges et des règles d'accès distinctes.

Vérifiez les règles de rôles dans le code et les paramètres

Comparez les événements bruts d'un spectateur, d'un VIP, d'un modérateur et du propriétaire du canal avec un texte identique. Si l'événement du modérateur atteint l'application mais que le gestionnaire l'a ignoré, l'erreur se situe après la réception : dans la vérification du rôle, la liste noire, l'antispam ou le routage des commandes.

• Ramenez les logins à une seule casse avant la comparaison.
• Vérifiez mod=1 et la badge moderator, et non un ensemble fixe de balises.
• Définissez séparément les droits pour broadcaster, moderator, vip et le compte du bot lui-même.
• Vérifiez si le modérateur ne figure pas dans la liste d'ignorés, la liste de bannis ou la liste des utilisateurs interdits.
• Examinez l'ordre des conditions : l'antispam ou les mots interdits peuvent se déclencher avant la vérification du rôle.
• Assurez-vous que la commande n'est pas bloquée par une règle pour les messages avec mention, lien ou répétition de texte.

Une liste manuelle de pseudos ne convient que pour un diagnostic rapide. Son inconvénient est qu'elle devient obsolète après un changement de modérateurs, un renommage de compte ou une modification des rôles dans le canal.

Excluez le format de commande, les limites et l'ignoré caché

Le bot peut voir le message et choisir délibérément de ne pas répondre. Vérifiez le cooldown de la commande, la limite de messages d'un même utilisateur, la protection contre les répétitions, le filtre d'emojis et de mots interdits. Les modérateurs envoient souvent des commandes rapidement et peuvent tomber sous l'antispam au même titre que les spectateurs.

Testez séparément une phrase ordinaire et une commande avec préfixe. Si la phrase figure dans le log mais que la commande n'atteint pas le résultat du traitement, vérifiez le préfixe, la disposition du clavier, les espaces, les caractères invisibles et les arguments. Les commandes avec slash et les actions de modération n'arrivent pas toujours sous forme de texte ordinaire attendu par le gestionnaire.

Enregistrez la raison de la décision pour chaque message

Pour le diagnostic, conservez l'heure, la source de l'événement, le canal, l'ID de l'auteur, le type de message, les balises et le résultat du traitement. Le texte peut être masqué s'il n'est pas nécessaire pour trouver l'erreur. Le log doit contenir une raison précise : message non reçu, rôle non reconnu, préfixe non validé, cooldown déclenché, utilisateur ignoré ou abonnement EventSub désactivé.

N'enregistrez pas dans les logs ordinaires les jetons OAuth, le secret de l'application, les adresses de webhooks et les en-têtes d'autorisation complets. Ces données sont pratiques pour le débogage, mais leur fuite peut ouvrir l'accès au bot et aux paramètres de l'application.

Check-list de diagnostic dans l'ordre

1. Envoyez une même phrase et une même commande depuis un spectateur et un modérateur.
2. Vérifiez le log brut et déterminez si le message est arrivé via IRC, EventSub ou les deux sources.
3. Si IRC ne reçoit pas les messages, vérifiez le compte du bot, le nom du canal, le jeton et la connexion réussie au chat.
4. Si le message IRC est arrivé, assurez-vous que les balises sont activées, puis vérifiez mod=1 et badges=moderator/1.
5. Si mod=1 est absent, vérifiez la confirmation de twitch.tv/tags et distinguez moderator/1, vip/1 et broadcaster/1.
6. Vérifiez le jeton via validate : pour IRC, chat:read est nécessaire ; pour les messages EventSub — user:read:chat.
7. En cas de fonctionnement via EventSub, vérifiez channel.chat.message, le statut enabled, condition et transport dans la liste des abonnements.
8. Comparez le traitement des rôles, la liste d'ignorés, l'antispam, le préfixe, le cooldown et les mots interdits.
9. Ajoutez au log la raison explicite pour laquelle chaque message est accepté, ignoré ou rejeté.