Por que o bot da Twitch ignora as mensagens dos moderadores

Primeiro, determine em que etapa a mensagem se perde

Verifique se o bot recebe mensagens normais no mesmo canal. Se os logs não mostrarem nem espectadores nem moderadores, o problema geralmente está na autorização, na conexão com o chat ou no nome do canal. Se os espectadores aparecem, mas as mensagens do moderador não, procure a causa no filtro de cargos, nas tags IRC ou na assinatura do EventSub.

Observe não apenas a resposta do bot no chat, mas o registro dos eventos recebidos. A mensagem pode chegar à aplicação, mas não acionar o comando por causa de prefixo, cooldown, palavras bloqueadas, lista de ignorados ou verificação de permissões. Para testar, envie de um espectador e de um moderador a mesma frase curta e depois o mesmo comando.

Verifique o canal, a conta do bot e a conexão IRC

Confirme que o bot entrou no canal correto e com a conta que deve ler o chat. Após renomear o canal, trocar o login ou alternar entre ambiente de teste e de produção, a aplicação pode continuar online, mas escutando outro chat.

No log de conexão devem aparecer a autorização bem-sucedida, o nick do bot e o comando de entrada no canal. Após uma queda de conexão, verifique não só as tentativas de reconexão, mas também se houve de fato um novo login bem-sucedido. A reconexão automática sem registro de erro esconde token expirado, senha OAuth incorreta ou erro no nome do canal.

Verifique o token OAuth e as permissões de leitura

O token deve pertencer à conta pela qual o bot lê o chat. Não o confunda com o token do streamer: as permissões do dono do canal não são transferidas para uma conta de bot separada. Para ler mensagens via IRC, é necessário o scope chat:read.

Se as mensagens forem recebidas via EventSub, para o evento de chat é necessário um token de usuário com a permissão user:read:chat. Dependendo do esquema de autorização e de quem cria a assinatura, também podem ser necessárias permissões para o acesso do bot ao canal, incluindo channel:bot. Não adicione scopes aleatoriamente: confira-os com o esquema de assinatura atual e com a conta em nome da qual ela é criada.

Para verificar a validade do token de usuário e a lista de permissões concedidas, use a requisição:

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

Na resposta, verifique o login, o identificador do usuário, o prazo de validade e o array scopes. Se chat:read ou user:read:chat estiver ausente, será necessário autorizar novamente com o conjunto de permissões correto. A desvantagem dessa solução é que os tokens antigos e as sessões salvas precisam ser substituídos na configuração do bot, caso contrário ele continuará operando com as permissões anteriores.

Separe o diagnóstico de IRC e EventSub

IRC e EventSub entregam mensagens por caminhos diferentes. O IRC transmite o fluxo do chat por uma conexão persistente: no log bruto é preciso encontrar a linha PRIVMSG do moderador. O EventSub entrega o evento channel.chat.message por meio de uma assinatura de API criada: aqui se verificam o status, o condition e o transporte de entrega.

Se o bot usar as duas fontes, registre no log a origem de cada evento. Caso contrário, uma mensagem pode ser processada duas vezes, e a falha de um transporte passará despercebida. Se apenas o EventSub for usado, a ausência de conexão IRC não é considerada erro. A desvantagem do esquema EventSub é que, com uma assinatura incorreta ou desativada, o bot não verá mensagem alguma, mesmo com o token funcionando.

Verifique a assinatura EventSub para mensagens de chat

Na lista de assinaturas, encontre o evento channel.chat.message. O registro deve ter status ativo. No condition, verifique o broadcaster_user_id — que é o identificador do canal do streamer — e o user_id do usuário que recebe os eventos. Um erro em qualquer um desses IDs costuma se manifestar como ausência seletiva de mensagens.

Solicite a lista de assinaturas via GET /helix/eventsub/subscriptions. Na resposta, verifique type, status, condition e transport. O status enabled significa que a assinatura está ativa; notificações de falha na entrega, registro removido ou outro canal indicarão a causa. Para essa requisição, use o token e o Client ID da aplicação que criou a assinatura.

Não se baseie apenas na presença do registro no painel ou no banco de dados do bot. A assinatura pode ter sido criada para um canal de teste, removida após erro de entrega ou pertencer a outra aplicação. A desvantagem da verificação via API é que ela mostra a configuração da assinatura, mas não explica a lógica de filtragem dentro do próprio handler.

Ative as tags IRC e verifique o cargo do autor

Se a verificação de permissões for baseada em IRC, o cliente deve solicitar a capability twitch.tv/tags. Sem as tags, o bot pode receber o texto e o nick do autor, mas não ver os campos mod e badges. Nesse caso, os comandos normais chegam, mas as regras de moderador geram uma recusa falsa.

Na mensagem bruta do moderador, procure mod=1 e badges=moderator/1. O campo user-type pode estar ausente, vazio ou não corresponder ao cargo atual, então não o use como único indicador. O parser deve tratar corretamente valores vazios de tags e caracteres escapados; a desvantagem da abordagem IRC está justamente na necessidade de interpretar esse formato por conta própria.

Se mod=1 não estiver presente, primeiro confirme que a capability para as tags foi realmente confirmada pelo servidor, e não apenas enviada pelo cliente. Depois verifique badges. O valor moderator/1 indica moderador, broadcaster/1 indica o dono do canal. O VIP geralmente tem a badge vip/1, mas o VIP não se torna moderador automaticamente. Não se deve considerar o streamer e o VIP como moderadores pelo nick, pela cor ou pelo display-name: determine o cargo pelas badges e por regras de acesso específicas.

Verifique as regras de cargos no código e nas configurações

Compare os eventos brutos de um espectador, de um VIP, de um moderador e do dono do canal com o mesmo texto. Se o evento do moderador chegou à aplicação, mas o handler o ignorou, o erro está após o recebimento: na verificação de cargo, na lista negra, no antispam ou no roteamento de comandos.

• Padronize os logins para o mesmo formato de maiúsculas e minúsculas antes de comparar.
• Verifique mod=1 e a badge moderator, e não um conjunto fixo de tags.
• Defina separadamente as permissões para broadcaster, moderator, vip e para a própria conta do bot.
• Verifique se o moderador não entrou na lista de ignorados, na lista de banidos ou na lista de usuários proibidos.
• Observe a ordem das condições: o antispam ou as palavras bloqueadas podem ser acionados antes da verificação de cargo.
• Confirme que o comando não é bloqueado por uma regra para mensagens com menção, link ou repetição de texto.

Uma lista manual de nicks serve apenas para diagnóstico rápido. Sua desvantagem é que ela fica desatualizada após mudanças de moderadores, renomeação de conta ou alteração de cargos no canal.

Exclua o formato do comando, os limites e o ignore oculto

O bot pode ver a mensagem e deliberadamente não responder. Verifique o cooldown do comando, o limite de mensagens de um mesmo usuário, a proteção contra repetições, o filtro de emojis e de palavras bloqueadas. Os moderadores costumam enviar comandos rapidamente e podem cair no antispam como os espectadores.

Teste separadamente uma frase comum e um comando com prefixo. Se a frase está no log, mas o comando não chegou ao resultado do processamento, verifique o prefixo, o layout do teclado, os espaços, os caracteres invisíveis e os argumentos. Comandos com barra e ações de moderação nem sempre chegam como texto comum que o handler espera.

Registre o motivo da decisão para cada mensagem

Para diagnóstico, salve o horário, a origem do evento, o canal, o ID do autor, o tipo de mensagem, as tags e o resultado do processamento. O texto pode ser mascarado se não for necessário para localizar o erro. O log deve conter o motivo específico: mensagem não recebida, cargo não reconhecido, prefixo não aceito, cooldown acionado, usuário na lista de ignorados ou assinatura EventSub desativada.

Não registre nos logs comuns tokens OAuth, o secret da aplicação, endereços de webhook e cabeçalhos de autorização completos. Esses dados são úteis na depuração, mas seu vazamento pode abrir acesso ao bot e às configurações da aplicação.

Checklist de diagnóstico em ordem

1. Envie a mesma frase e o mesmo comando de um espectador e de um moderador.
2. Verifique o log bruto e determine se a mensagem chegou via IRC, EventSub ou ambas as fontes.
3. Se o IRC não receber mensagens, confira a conta do bot, o nome do canal, o token e o login bem-sucedido no chat.
4. Se a mensagem IRC chegou, confirme que as tags estão ativadas e depois verifique mod=1 e badges=moderator/1.
5. Se mod=1 estiver ausente, verifique a confirmação de twitch.tv/tags e diferencie moderator/1, vip/1 e broadcaster/1.
6. Verifique o token via validate: para IRC é necessário chat:read; para mensagens via EventSub, user:read:chat.
7. Ao operar via EventSub, verifique channel.chat.message, o status enabled, o condition e o transport na lista de assinaturas.
8. Compare o tratamento de cargos, a lista de ignorados, o antispam, o prefixo, o cooldown e as palavras bloqueadas.
9. Adicione ao log o motivo explícito pelo qual cada mensagem foi aceita, ignorada ou rejeitada.