Perché il bot di Twitch salta i messaggi dei moderatori

Prima stabilisci in quale fase si perde il messaggio

Verifica se il bot riceve i messaggi normali nello stesso canale. Se nei log non compaiono né spettatori né moderatori, il problema di solito è nell'autorizzazione, nella connessione alla chat o nel nome del canale. Se gli spettatori sono visibili ma le battute del moderatore mancano, cerca la causa nel filtro dei ruoli, nei tag IRC o nella sottoscrizione EventSub.

Non guardare solo la risposta del bot in chat, ma il registro degli eventi in ingresso. Il messaggio può arrivare all'applicazione ma non avviare il comando a causa del prefisso, del cooldown, delle stop-word, della lista di ignorati o del controllo dei permessi. Per il test invia da uno spettatore e da un moderatore la stessa frase breve, poi lo stesso comando.

Controlla il canale, l'account del bot e la connessione IRC

Assicurati che il bot sia entrato proprio nel canale giusto e con l'account che deve leggere la chat. Dopo la rinomina del canale, il cambio di login o il passaggio tra ambiente di test e di produzione, l'applicazione può restare online ma ascoltare un'altra chat.

Nel log della connessione devono essere visibili l'autorizzazione riuscita, il nick del bot e il comando di ingresso nel canale. Dopo un'interruzione della connessione controlla non solo i tentativi di riconnessione, ma anche l'effettivo nuovo ingresso riuscito. La riconnessione automatica senza registrazione dell'errore nasconde un token scaduto, una password OAuth errata o un errore nel nome del canale.

Controlla il token OAuth e i permessi di lettura

Il token deve appartenere all'account tramite cui il bot legge la chat. Non confonderlo con il token dello streamer: i permessi del proprietario del canale non vengono trasferiti a un account bot separato. Per leggere i messaggi tramite IRC serve lo scope chat:read.

Se i messaggi vengono ricevuti tramite EventSub, per l'evento della chat serve un token utente con il permesso user:read:chat. A seconda dello schema di autorizzazione e di chi crea la sottoscrizione, possono servire anche i permessi per l'accesso del bot al canale, incluso channel:bot. Non aggiungere scope a caso: confrontali con lo schema di sottoscrizione attuale e con l'account per conto del quale viene creata.

Puoi verificare la validità del token utente e l'elenco dei permessi concessi con la richiesta:

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

Nella risposta controlla il login, l'identificativo utente, la scadenza e l'array scopes. Se chat:read o user:read:chat manca, sarà necessaria una nuova autorizzazione con il set di permessi corretto. Il difetto di questa soluzione è che i vecchi token e le sessioni salvate vanno sostituiti nella configurazione del bot, altrimenti continuerà a funzionare con i permessi precedenti.

Separa la diagnostica di IRC ed EventSub

IRC ed EventSub consegnano i messaggi tramite percorsi diversi. IRC trasmette il flusso della chat su una connessione persistente: nel log grezzo devi trovare la riga PRIVMSG del moderatore. EventSub trasmette l'evento channel.chat.message tramite una sottoscrizione API creata: qui si controllano lo stato, la condition e il transport di consegna.

Se il bot usa entrambe le fonti, registra nel log la fonte di ogni evento. Altrimenti un messaggio può essere elaborato due volte, e il guasto di un transport resterà invisibile. Se si usa solo EventSub, l'assenza della connessione IRC non è considerata un errore. Il difetto dello schema EventSub è che con una sottoscrizione errata o disattivata il bot non vedrà affatto i messaggi, anche con un token funzionante.

Controlla la sottoscrizione EventSub ai messaggi della chat

Nell'elenco delle sottoscrizioni trova l'evento channel.chat.message. La voce deve avere uno stato attivo. Nella condition controlla broadcaster_user_id — l'identificativo del canale dello streamer — e user_id dell'utente che riceve gli eventi. Un errore in uno qualsiasi di questi ID spesso si presenta come assenza selettiva dei messaggi.

Richiedi l'elenco delle sottoscrizioni tramite GET /helix/eventsub/subscriptions. Nella risposta controlla type, status, condition e transport. Lo stato enabled significa che la sottoscrizione è attiva; le notifiche di errore di consegna, una voce rimossa o un altro canale indicheranno la causa. Per questa richiesta usa il token e il Client ID dell'applicazione che ha creato la sottoscrizione.

Non basarti solo sulla presenza della voce nel pannello o nel database del bot. La sottoscrizione potrebbe essere stata creata per un canale di test, rimossa dopo un errore di consegna o appartenere a un'altra applicazione. Il difetto del controllo tramite API è che mostra la configurazione della sottoscrizione, ma non spiega la logica di filtraggio all'interno dell'handler stesso.

Abilita i tag IRC e controlla il ruolo dell'autore

Se il controllo dei permessi si basa su IRC, il client deve richiedere la capability twitch.tv/tags. Senza i tag il bot può ricevere il testo e il nick dell'autore, ma non vedere i campi mod e badges. In tal caso i comandi normali arrivano, mentre le regole per i moderatori danno un rifiuto falso.

Nel messaggio grezzo del moderatore cerca mod=1 e badges=moderator/1. Il campo user-type può mancare, essere vuoto o non corrispondere al ruolo attuale, quindi non usarlo come unico indicatore. Il parser deve gestire correttamente i valori vuoti dei tag e i caratteri con escape; il difetto dell'approccio IRC sta proprio nella necessità di analizzare questo formato da soli.

Se mod=1 non c'è, prima assicurati che la capability per i tag sia effettivamente confermata dal server, e non solo inviata dal client. Poi controlla badges. Il valore moderator/1 indica un moderatore, broadcaster/1 il proprietario del canale. Il VIP di solito ha il badge vip/1, ma il VIP non diventa automaticamente moderatore. Non considerare lo streamer e il VIP come moderatori in base al nick, al colore o al display-name: determina il ruolo tramite badges e regole di accesso separate.

Controlla le regole dei ruoli nel codice e nelle impostazioni

Confronta gli eventi grezzi di uno spettatore, di un VIP, di un moderatore e del proprietario del canale con lo stesso testo. Se l'evento del moderatore è arrivato all'applicazione ma l'handler l'ha saltato, l'errore si trova dopo la ricezione: nel controllo del ruolo, nella blacklist, nell'antispam o nell'instradamento dei comandi.

• Porta i login allo stesso caso prima del confronto.
• Controlla mod=1 e il badge moderator, non un unico set fisso di tag.
• Definisci separatamente i permessi per broadcaster, moderator, vip e l'account del bot stesso.
• Verifica che il moderatore non sia finito nella lista di ignorati, nella ban-list o nell'elenco degli utenti vietati.
• Guarda l'ordine delle condizioni: l'antispam o le stop-word possono scattare prima del controllo del ruolo.
• Assicurati che il comando non sia bloccato da una regola per i messaggi con menzione, link o ripetizione del testo.

La lista manuale dei nick è adatta solo per una diagnostica rapida. Il suo difetto è che diventa obsoleta dopo il cambio dei moderatori, la rinomina dell'account o la modifica dei ruoli nel canale.

Escludi il formato del comando, i limiti e l'ignoramento nascosto

Il bot può vedere il messaggio e non rispondere di proposito. Controlla il cooldown del comando, il limite di messaggi da un singolo utente, la protezione dalle ripetizioni, il filtro emoji e le stop-word. I moderatori non di rado inviano comandi rapidamente e possono incorrere nell'antispam come gli spettatori.

Testa separatamente una frase normale e un comando con prefisso. Se la frase è nel log ma il comando non è arrivato al risultato dell'elaborazione, controlla il prefisso, la disposizione della tastiera, gli spazi, i caratteri invisibili e gli argomenti. I comandi con slash e le azioni di moderazione non sempre arrivano come testo normale che l'handler si aspetta.

Registra il motivo della decisione per ogni messaggio

Per la diagnostica salva l'ora, la fonte dell'evento, il canale, l'ID dell'autore, il tipo di messaggio, i tag e l'esito dell'elaborazione. Il testo può essere mascherato se non serve per individuare l'errore. Nel log deve esserci un motivo concreto: messaggio non ricevuto, ruolo non riconosciuto, prefisso non superato, cooldown scattato, utente ignorato o sottoscrizione EventSub disattivata.

Non scrivere nei log normali i token OAuth, il secret dell'applicazione, gli indirizzi dei webhook e le intestazioni di autorizzazione complete. Questi dati sono utili in fase di debug, ma la loro fuga può aprire l'accesso al bot e alle impostazioni dell'applicazione.

Checklist diagnostica in ordine

1. Invia la stessa frase e lo stesso comando da uno spettatore e da un moderatore.
2. Controlla il log grezzo e stabilisci se il messaggio è arrivato tramite IRC, EventSub o entrambe le fonti.
3. Se IRC non riceve i messaggi, verifica l'account del bot, il nome del canale, il token e l'ingresso riuscito in chat.
4. Se il messaggio IRC è arrivato, assicurati che i tag siano abilitati, poi controlla mod=1 e badges=moderator/1.
5. Se mod=1 manca, controlla la conferma di twitch.tv/tags e distingui moderator/1, vip/1 e broadcaster/1.
6. Controlla il token tramite validate: per IRC serve chat:read, per i messaggi EventSub — user:read:chat.
7. Se lavori tramite EventSub, controlla channel.chat.message, lo stato enabled, la condition e il transport nell'elenco delle sottoscrizioni.
8. Confronta l'elaborazione dei ruoli, la lista di ignorati, l'antispam, il prefisso, il cooldown e le stop-word.
9. Aggiungi al log il motivo esplicito per cui ogni messaggio è accettato, ignorato o rifiutato.