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（ストリーマーのチャンネル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は通常vip/1バッジを持ちますが、VIPが自動的にモデレーターになるわけではありません。ストリーマーやVIPをニックネーム、色、display-nameでモデレーターと判断すべきではありません。ロールはbadgesと個別のアクセスルールで判断してください。

コードと設定のロールルールを確認する

同じテキストで、視聴者、VIP、モデレーター、チャンネル所有者からの生イベントを比較してください。モデレーターからのイベントがアプリケーションに届いているのにハンドラーがスキップした場合、エラーは受信後の段階、つまりロールチェック、ブラックリスト、アンチスパム、コマンドルーティングにあります。

• 比較する前にログイン名を同じ大文字小文字に揃えてください。
• 固定のタグセットではなく、mod=1とbadge moderatorを確認してください。
• broadcaster、moderator、vip、ボット自身のアカウントの権限を個別に定義してください。
• モデレーターが無視リスト、禁止リスト、ブロックユーザーリストに入っていないか確認してください。
• 条件の順序を確認してください。アンチスパムやストップワードがロールチェックより先に発動することがあります。
• メンション、リンク、テキストの繰り返しを含むメッセージに対するルールでコマンドがブロックされていないことを確認してください。

ニックネームの手動リストは簡単な診断にのみ適しています。その欠点は、モデレーターの変更、アカウント名の変更、チャンネルでのロール変更の後に古くなることです。

コマンド形式、制限、隠れた無視を除外する

ボットはメッセージを認識していても、意図的に応答しないことがあります。コマンドのクールダウン、1ユーザーあたりのメッセージ制限、繰り返し防止、絵文字フィルター、ストップワードを確認してください。モデレーターはコマンドを素早く送信することが多く、視聴者と同じようにアンチスパムに引っかかることがあります。

通常のフレーズとプレフィックス付きのコマンドを別々にテストしてください。フレーズはログにあるのにコマンドが処理結果に達していない場合は、プレフィックス、キーボードレイアウト、スペース、不可視文字、引数を確認してください。スラッシュ付きのコマンドやモデレーションアクションは、ハンドラーが期待する通常のテキスト形式では届かないことがあります。

各メッセージの判定理由を記録する

診断のために、時刻、イベントソース、チャンネル、投稿者ID、メッセージタイプ、タグ、処理結果を保存してください。エラーの特定に不要であれば、テキストはマスクしてもかまいません。ログには具体的な理由があるべきです。メッセージ未受信、ロール未認識、プレフィックス不一致、クールダウン発動、ユーザーが無視対象、EventSub購読が無効、などです。

通常のログにOAuthトークン、アプリケーションシークレット、ウェブフックURL、完全な認証ヘッダーを記録しないでください。これらのデータはデバッグに便利ですが、漏洩するとボットやアプリケーション設定へのアクセスが可能になります。

順を追った診断チェックリスト

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. 各メッセージが受け入れられた、無視された、拒否された明示的な理由をログに追加します。