Twitch 봇이 모더레이터의 메시지를 건너뛰는 이유

먼저 메시지가 어느 단계에서 사라지는지 파악하세요

봇이 같은 채널에서 일반 메시지를 수신하는지 확인하세요. 로그에 시청자도 모더레이터도 없다면 문제는 보통 인증, 채팅 연결 또는 채널 이름에 있습니다. 시청자는 보이는데 모더레이터의 발언이 없다면 역할 필터, IRC 태그 또는 EventSub 구독에서 원인을 찾으세요.

채팅에서 봇의 응답만 보지 말고 수신 이벤트 로그를 확인하세요. 메시지가 애플리케이션에 도달했더라도 접두사, 쿨다운, 금지어, 무시 목록 또는 권한 검사 때문에 명령이 실행되지 않을 수 있습니다. 테스트로 시청자와 모더레이터가 동일한 짧은 문구를 보내고, 그다음 동일한 명령을 보내 보세요.

채널, 봇 계정 및 IRC 연결을 확인하세요

봇이 채팅을 읽어야 하는 계정으로 정확히 해당 채널에 입장했는지 확인하세요. 채널 이름이 변경되거나 로그인이 바뀌거나 테스트 환경과 운영 환경을 전환한 후 애플리케이션이 온라인 상태로 남아 있지만 다른 채팅을 듣고 있을 수 있습니다.

연결 로그에는 성공적인 인증, 봇 닉네임 및 채널 입장 명령이 보여야 합니다. 연결이 끊긴 후에는 재연결 시도뿐만 아니라 새로 성공적으로 입장했는지도 확인하세요. 오류를 기록하지 않는 자동 재연결은 만료된 토큰, 잘못된 OAuth 비밀번호 또는 채널 이름 오류를 숨깁니다.

OAuth 토큰과 읽기 권한을 확인하세요

토큰은 봇이 채팅을 읽는 계정의 것이어야 합니다. 스트리머의 토큰과 혼동하지 마세요. 채널 소유자의 권한은 별도의 봇 계정에 이전되지 않습니다. IRC를 통해 메시지를 읽으려면 chat:read 스코프가 필요합니다.

EventSub를 통해 메시지를 수신하는 경우 채팅 이벤트에는 user:read:chat 권한이 있는 사용자 토큰이 필요합니다. 인증 방식과 구독을 생성하는 주체에 따라 봇이 채널에 접근하기 위한 권한(예: channel:bot)도 필요할 수 있습니다. 스코프를 추측해서 추가하지 말고 현재 구독 방식과 구독을 생성하는 계정에 맞춰 확인하세요.

사용자 토큰의 유효성과 부여된 권한 목록은 다음 요청으로 확인할 수 있습니다:

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

응답에서 로그인, 사용자 ID, 만료 시간 및 scopes 배열을 확인하세요. chat:read 또는 user:read:chat이 없으면 필요한 권한 집합으로 다시 인증해야 합니다. 이 방법의 단점은 기존 토큰과 저장된 세션을 봇 구성에서 교체해야 하며, 그렇지 않으면 봇이 이전 권한으로 계속 작동한다는 것입니다.

IRC와 EventSub 진단을 분리하세요

IRC와 EventSub는 서로 다른 경로로 메시지를 전달합니다. IRC는 지속적인 연결을 통해 채팅 스트림을 전송하므로 원시 로그에서 모더레이터의 PRIVMSG 줄을 찾아야 합니다. EventSub는 생성된 API 구독을 통해 channel.chat.message 이벤트를 전달하므로 여기서는 상태, condition 및 전송 방식을 확인합니다.

봇이 두 소스를 모두 사용하는 경우 각 이벤트의 소스를 로그에 기록하세요. 그렇지 않으면 하나의 메시지가 두 번 처리될 수 있고 한 전송 방식의 장애가 눈에 띄지 않을 수 있습니다. EventSub만 사용하는 경우 IRC 연결이 없는 것은 오류로 간주되지 않습니다. EventSub 방식의 단점은 구독이 잘못되었거나 비활성화된 경우 토큰이 정상이더라도 봇이 메시지를 전혀 보지 못한다는 것입니다.

채팅 메시지에 대한 EventSub 구독을 확인하세요

구독 목록에서 channel.chat.message 이벤트를 찾으세요. 해당 항목은 활성 상태여야 합니다. condition에서 broadcaster_user_id(스트리머 채널의 식별자)와 이벤트를 수신하는 사용자의 user_id를 확인하세요. 이 ID 중 하나라도 잘못되면 종종 메시지가 선택적으로 누락되는 것처럼 보입니다.

GET /helix/eventsub/subscriptions로 구독 목록을 요청하세요. 응답에서 type, status, condition 및 transport를 확인하세요. status가 enabled이면 구독이 활성 상태입니다. 전송 실패 알림, 삭제된 항목 또는 다른 채널은 원인을 나타냅니다. 이 요청에는 구독을 생성한 애플리케이션의 토큰과 Client ID를 사용하세요.

패널이나 봇 데이터베이스에 항목이 있다는 것만으로 판단하지 마세요. 구독이 테스트 채널용으로 생성되었거나 전송 오류 후 삭제되었거나 다른 애플리케이션에 속할 수 있습니다. API를 통한 확인의 단점은 구독 구성을 보여주지만 핸들러 내부의 필터링 로직은 설명하지 못한다는 것입니다.

IRC 태그를 활성화하고 작성자 역할을 확인하세요

권한 검사가 IRC를 기반으로 하는 경우 클라이언트는 twitch.tv/tags capability를 요청해야 합니다. 태그가 없으면 봇은 텍스트와 작성자 닉네임을 받을 수 있지만 mod 및 badges 필드를 보지 못합니다. 이 경우 일반 명령은 도착하지만 모더레이터 규칙은 잘못된 거부를 반환합니다.

모더레이터의 원시 메시지에서 mod=1 및 badges=moderator/1을 찾으세요. user-type 필드는 없거나 비어 있거나 현재 역할과 일치하지 않을 수 있으므로 유일한 기준으로 사용하지 마세요. 파서는 빈 태그 값과 이스케이프된 문자를 올바르게 처리해야 합니다. IRC 방식의 단점은 바로 이 형식을 직접 파싱해야 한다는 점입니다.

mod=1이 없으면 먼저 태그에 대한 capability가 클라이언트에 의해 전송되었을 뿐만 아니라 서버에 의해 실제로 확인되었는지 확인하세요. 그런 다음 badges를 확인하세요. moderator/1 값은 모더레이터, broadcaster/1은 채널 소유자를 의미합니다. VIP는 보통 vip/1 배지를 가지지만 VIP가 자동으로 모더레이터가 되지는 않습니다. 스트리머와 VIP를 닉네임, 색상 또는 display-name으로 모더레이터로 간주하지 말고 badges 및 별도의 접근 규칙으로 역할을 판별하세요.

코드와 설정의 역할 규칙을 확인하세요

동일한 텍스트로 시청자, VIP, 모더레이터 및 채널 소유자의 원시 이벤트를 비교하세요. 모더레이터의 이벤트가 애플리케이션에 도달했지만 핸들러가 건너뛰었다면 오류는 수신 이후에 있습니다: 역할 검사, 블랙리스트, 안티스팸 또는 명령 라우팅에 있습니다.

• 비교하기 전에 로그인을 하나의 대소문자로 통일하세요.
• 하나의 고정된 태그 집합이 아니라 mod=1 및 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. 각 메시지가 수락, 무시 또는 거부된 명확한 이유를 로그에 추가하세요.