Discordの特権ゲートウェイインテントは、オプトインの3つの権限（プレゼンス、サーバーメンバー、メッセージ内容）です。Discordがそのデータをゲートウェイ経由で送信する前に、ボットの所有者がデベロッパーポータルでオンにする必要があります。これらが存在するのは、メンバー一覧とメッセージ本文が、デフォルトで機密性の高いデータだからです。1つでも設定を忘れると、ボットは大きなエラーを出しません。必要なイベントを黙って受け取れなくなるだけです。「ボットはオンラインなのに何もしない」という問題の原因が、インテントのスイッチであることが多いのはそのためです。
ゲートウェイインテントとは実際には何か
ボットがDiscordに接続しても、参加しているすべてのサーバーで起きるすべてのイベントを自動的に受け取るわけではありません。インテントと呼ばれるイベントのカテゴリを購読します。メッセージイベント、ボイス状態のイベント、サーバー更新のイベントなどです。ほとんどのインテントは、コード内で宣言するだけで無料で使え、Discordは確認なしで付与します。3つだけは違います。これらは特権インテントと呼ばれます。その背後にあるデータ、つまり誰がサーバーにいるか、メンバーが何を入力しているかは非常に強力なため、コードで宣言するだけでなく、ボットの所有者がデベロッパーポータルで明示的にオプトインすることを求めているのです。
ボットのコードが特権インテントを要求しても、所有者がそのアプリケーションでオンにしていなければ、Discordはログインを完全に拒否します。ボットが一部の機能だけで接続されるわけではありません。まったく接続されず、ゲートウェイは「disallowed intents」というエラーで切断されます。
3つの特権インテント
- プレゼンスインテント。すべてのメンバーのオンライン、退席中、オフラインのステータスと、カスタムアクティビティ。ライブのプレゼンス情報を表示するボットで使われます。ほとんどのチケット、モデレーション、コマースのボットには必要ありません。Noxyrも含まれます。
- サーバーメンバーインテント。メンバーの完全な一覧に加えて、参加と退出のイベント、ロールの変更、ニックネームの更新。参加メッセージ、メンバー数、レイド対策の検出を支えているのがこのインテントです。
- メッセージ内容インテント。メッセージが送信されたという事実だけでなく、メッセージの実際の本文です。これがないと、ボットは誰かがチャンネルに投稿したことはわかっても、何を入力したかは読めません。
Noxyrのコードは、3つのうち2つ、サーバーメンバーインテントとメッセージ内容インテントを要求します。プレゼンスインテントはNoxyrのどの機能にも使われていないので、要求されることはなく、オンにする必要もありません。
サーバーメンバーインテントがないと何が動かなくなるか
サーバーメンバーインテントがあると、ボットは GUILD_MEMBER_ADD と GUILD_MEMBER_REMOVE のイベントを受け取れます。これは、ほとんどのメンバー関連の機能が依存している参加と退出のイベントです。
- 参加メッセージ。参加メッセージは、参加時に発火します。インテントがないと、ボットは参加イベントを受け取れないため、何も投稿されず、自動ロールも付与されません。
- メンバー数。リアルタイムのメンバー数チャンネルやウィジェットは、同じ参加と退出のイベントで更新されます。インテントがないと、最後に見た数字のまま止まります。
- アンチニュークとレイド対策。大量参加のレイドを検出することも、怪しいロールやニックネームの変更を監視することも、メンバーのイベントに依存しています。インテントをオフにすると、その検出機能はすべて機能しなくなります。
- 認証フロー。メンバーの参加日、ロール、アカウントの作成日を確認するゲートは、インテントが提供するメンバーのオブジェクトを必要とします。
メッセージ内容インテントがないと何が動かなくなるか
メッセージ内容インテントは、メッセージの実際の本文を制御します。このインテントがなくても、ボットはチャンネルにメッセージが届いたことと、誰が送ったかはわかります。ただし、何が書かれたかは読めません。
- 自動応答。「返金」や「支払い方法」のようなトリガーワードに一致させるには、メッセージの本文を読む必要があります。内容がなければ、一致もせず、返信もしません。
- AIチャットの返信。チャンネルでの質問に答えたり、メンションに反応したりするAIアシスタントには、質問そのものが必要です。インテントがないと、誰かが話したことはわかっても、モデルに送る内容がありません。
- チケットのトランスクリプト。スタッフとメンバーが実際にチケットで話した内容を記録するトランスクリプトには、ログとしてメッセージ内容が必要です。ないと、内容のないタイムスタンプとユーザー名の一覧になってしまいます。
- プレフィックスベースのモデレーション。禁止ワード、招待リンク、スパムのパターンをメッセージから検出する機能は、自動応答と同じようにメッセージ内容を読みます。
スラッシュコマンドはどちらの場合も影響を受けません。Discordはコマンドの入力を通常のメッセージとは別に配信するからです。このインテントに依存するのは、通常のメッセージでメンバーが入力した内容を読む機能に限られます。
デベロッパーポータルでインテントを有効にする方法
- Discordデベロッパーポータルを開き、ボットのアプリケーションを選択します。
- 左のサイドバーでBotをクリックします。
- Privileged Gateway Intentsまでスクロールします。
- サーバーメンバーインテントとメッセージ内容インテントをオンにします（ライブのステータスデータが特に必要なボットの場合のみ、プレゼンスインテントを追加します）。
- 変更を保存し、ボットを再起動または再接続して、次のログイン時に新しいインテントを反映させます。
このスイッチは、次のゲートウェイ接続で反映されます。すでにログインしているボットには即座には反映されません。セッションの途中でインテントをオフにすると、通常はDiscordによって切断されるため、インテントを再度オンにした後に再接続が必要になります。
100サーバーの認証ルール
100サーバー未満のボットであれば、ポータルでスイッチを切り替えるだけで十分です。ボットのインストール数が100サーバーを超えると、Discordはボットの認証を求めます。これは、所有者がボットを審査に提出して承認を受ける手続きです。この規模で特権インテントを使う前に必要になります。認証されていないボットが上限に達すると、すでに参加しているサーバーでは動き続けますが、認証を受けるか、厳密には必要としない特権インテントを外すまで、新しいサーバーには参加できなくなります。
これはDiscordのプラットフォームのルールであり、個々のボットのホストが制御できるものではありません。サーバーメンバーやメッセージ内容のような、データに関わるインテントを、ボットがそれをどう使うかについてDiscord自身の審査なしに大規模に配ることがないようにするためのルールです。
Noxyrがトークンを受け付ける前に両方のインテントを確認する理由
Noxyrのカスタムボット機能は、あなたが用意したボットトークンで機能一式を動かします。参加メッセージ、メンバー数、AIチャット、チケットのトランスクリプト、自動応答はすべて、上の2つのインテントに依存しています。そのため、ダッシュボードは、トークンを受け付ける前に、サーバーメンバーインテントとメッセージ内容インテントがオンになっているかを確認します。どちらかがオフのままトークンを貼り付けた場合は、事前に拒否されます。受け付けてから、後で混乱するゲートウェイエラーで静かに失敗するよりもよいからです。
ボットがすでに動いている後にインテントがオフにされた場合（数か月後に誰かがポータルでチェックを外した場合など）、Discordのゲートウェイはコード4013または4014で接続を閉じます。Noxyrのホスティングノードはその特定の切断コードを検出し、ボットを停止して、どの設定を直すべきかを平易な言葉で伝えるステータスメッセージを投稿します。サイレントな再接続ループに陥ったままにはしません。このエラーと、その他のオフラインの一般的な原因の詳細は、ゲートウェイエラー4004/4014のトラブルシューティングガイドにまとめています。
よくある質問
Noxyrのカスタムボットにプレゼンスインテントは必要ですか？いいえ。Noxyrが要求するのは、サーバーメンバーインテントとメッセージ内容インテントだけです。プレゼンスインテントはオフのままで構いません。
スイッチをオンにしたのに、ボットに「disallowed intents」と表示されるのはなぜですか？ゲートウェイが現在の状態を読み取るのは、新しいログインのときだけです。ポータルの設定を保存した後にボットを再起動すると、新しいインテントが適用された状態で再接続します。
メッセージ内容インテントをオンにすると、Discordがボットにメッセージ履歴を共有するのですか？いいえ。影響するのは、ボットが接続していて、そのチャンネルにアクセスできる状態で送信されたメッセージだけです。ボットがいなかった時期の過去のメッセージへのアクセスを、後から与えるものではありません。
特権インテントを要求すると、ボットがBANされますか？いいえ。参加メッセージ、自動応答、AIの返信など、それを必要とする機能のために要求して使うことこそ、特権インテントの用途です。認証は大規模なボットのためにあるもので、罰則ではありません。
セットアップの全手順はカスタムボットのドキュメントを、またはNoxyrを無料で追加して、トークンを使うカスタムボットではなくメインのボットを使えば、インテントの設定はまったく不要です。