Uprzywilejowane intenty gateway na Discordzie to trzy uprawnienia włączane świadomie (Presence, Server Members i Message Content), które właściciel bota musi aktywować w Developer Portal, zanim Discord zacznie wysyłać te dane przez gateway. Istnieją, bo listy członków i treść wiadomości są domyślnie wrażliwe. Jeśli pominiesz jedno z nich, bot nie zgłosi głośnego błędu - po prostu przestanie widzieć zdarzenia, których potrzebuje, dlatego tak często „bot jest online, ale nic nie robi” sprowadza się do przełącznika intentu.
Czym właściwie jest intent gateway
Gdy bot łączy się z Discordem, nie otrzymuje automatycznie każdego zdarzenia ze wszystkich serwerów, na których się znajduje. Subskrybuje kategorie zdarzeń zwane intentami: zdarzenia wiadomości, zdarzenia stanu głosowego, zdarzenia aktualizacji serwera i tak dalej. Większość intentów można zadeklarować w kodzie za darmo, a Discord przyznaje je bez pytania. Trzy są inne. Discord nazywa je uprzywilejowanymi, bo dane za nimi - dokładnie to, kto jest na serwerze i co członkowie piszą - są na tyle wrażliwe, że właściciel bota musi wyraźnie wyrazić zgodę w Developer Portal, a nie tylko w kodzie.
Jeśli kod bota żąda uprzywilejowanego intentu, ale właściciel nie włączył go dla tej aplikacji, Discord całkowicie odrzuca logowanie. Bot nie łączy się w okrojonym trybie; w ogóle się nie łączy, a gateway zamyka połączenie z błędem „disallowed intents”.
Trzy uprzywilejowane intenty
- Presence Intent. Status online/zaraz wracam/offline i niestandardowe aktywności każdego członka. Używają go boty pokazujące dane o obecności na żywo; większość botów do ticketów, moderacji i handlu, w tym Noxyr, go nie potrzebuje.
- Server Members Intent. Pełna lista członków oraz zdarzenia dołączenia i wyjścia, zmiany ról i aktualizacje pseudonimów. To intent stojący za wiadomościami powitalnymi, licznikami członków i wykrywaniem najazdów.
- Message Content Intent. Rzeczywisty tekst wiadomości, a nie sam fakt, że wiadomość została wysłana. Bez niego bot widzi, że ktoś coś napisał na kanale, ale nie wie, co dokładnie.
Kod Noxyr żąda dwóch z trzech: Server Members Intent i Message Content Intent. Presence Intent nie jest częścią żadnej funkcji Noxyr, więc nigdy nie jest żądany i nie musi być włączany.
Co się psuje bez Server Members Intent
Server Members Intent pozwala botowi odbierać zdarzenia GUILD_MEMBER_ADD i GUILD_MEMBER_REMOVE, czyli zdarzenia dołączenia i wyjścia, od których zależy niemal każda funkcja związana z członkami.
- Wiadomości powitalne. Wiadomość powitalna uruchamia się przy dołączeniu. Bez intentu bot nigdy nie dostaje zdarzenia dołączenia, więc nic się nie publikuje i nie jest przydzielana automatyczna rola.
- Liczba członków. Kanał lub widżet z liczbą członków aktualizuje się na podstawie tych samych zdarzeń dołączenia i wyjścia. Bez intentu zamarza na ostatnio widzianej liczbie.
- Ochrona przed anti-nuke i najazdami. Wykrywanie masowego najazdu dołączających lub obserwowanie podejrzanych zmian ról i pseudonimów zależy od zdarzeń członków. Wyłącz intent, a cała ta ścieżka wykrywania przestanie działać.
- Procesy weryfikacji. Każda bramka sprawdzająca datę dołączenia, role lub wiek konta potrzebuje obiektu członka, który dostarcza intent.
Co się psuje bez Message Content Intent
Message Content Intent kontroluje dostęp do rzeczywistego tekstu wiadomości. Bez tego intentu bot nadal widzi, że kanał otrzymał wiadomość i kto ją wysłał; po prostu nie może odczytać, co zostało napisane.
- Autoresponder. Dopasowanie słowa wyzwalającego, takiego jak „refund” albo „how do I pay”, wymaga odczytania tekstu wiadomości. Brak treści oznacza brak dopasowania i brak odpowiedzi.
- Odpowiedzi czatu AI. Asystent AI, który odpowiada na pytania na kanale lub po wzmiance, potrzebuje samego pytania. Bez intentu wie, że ktoś coś napisał, ale nie ma czego przesłać modelowi.
- Transkrypty ticketów. Transkrypt zapisujący to, co personel i członkowie faktycznie napisali w tickecie, potrzebuje treści wiadomości; bez niej dostajesz listę znaczników czasu i nazw użytkowników bez treści.
- Moderacja oparta na prefiksach. Wszystko, co skanuje wiadomości pod kątem zakazanych słów, linków do zaproszeń lub wzorców spamu, czyta treść tak samo jak autoresponder.
Komendy z ukośnikiem nie są dotknięte w żadnym przypadku, bo Discord dostarcza dane komend osobno od zwykłych wiadomości. Od tego intentu zależą konkretnie funkcje, które odczytują to, co członkowie wpisują w zwykłych wiadomościach.
Jak włączyć intenty w Developer Portal
- Otwórz Discord Developer Portal i wybierz aplikację bota.
- Kliknij Bot w lewym pasku bocznym.
- Przewiń do sekcji Privileged Gateway Intents.
- Włącz Server Members Intent i Message Content Intent (dodaj Presence Intent tylko wtedy, gdy bot naprawdę potrzebuje danych o statusie na żywo).
- Zapisz zmiany, a następnie zrestartuj lub połącz ponownie bota, by przy kolejnym logowaniu przejął nowe intenty.
Przełącznik działa przy kolejnym połączeniu z gateway, a nie natychmiast dla bota, który jest już zalogowany. Bot, który był w trakcie sesji, gdy intent został wyłączony, zwykle zostanie rozłączony przez Discord i trzeba go połączyć ponownie po ponownym włączeniu intentu.
Zasada weryfikacji przy 100 serwerach
Samo przełączenie w portalu wystarcza botowi na mniej niż 100 serwerach. Gdy liczba instalacji bota przekracza 100 serwerów, Discord wymaga przejścia przez weryfikację bota - proces przeglądu, w którym właściciel zgłasza bota do zatwierdzenia - zanim będzie mógł używać uprzywilejowanych intentów na tej skali. Niezweryfikowany bot, który osiągnie ten próg, dalej działa na serwerach, na których już jest, ale jest ograniczony w dołączaniu do nowych, dopóki weryfikacja nie zostanie przyznana lub nie zrezygnuje się z uprzywilejowanych intentów, których nie potrzebuje bezwzględnie.
To zasada platformy Discorda, a nie coś, co kontroluje jakikolwiek hosting botów. Istnieje po to, by wrażliwe dane, jak Server Members i Message Content, nie były rozdawane na dużą skalę bez przeglądu Discorda, co bot z nimi robi.
Dlaczego Noxyr sprawdza oba intenty, zanim zaakceptuje token
Funkcja Bota niestandardowego w Noxyr uruchamia pełny zestaw funkcji pod tokenem bota, który podajesz. Ponieważ wiadomości powitalne, liczby członków, czat AI, transkrypty ticketów i autorespondery zależą od dwóch wyżej wymienionych intentów, panel sprawdza, czy Server Members Intent i Message Content Intent są włączone, zanim w ogóle zaakceptuje twój token. Token wklejony przy wyłączonym którymkolwiek z tych intentów zostaje odrzucony od razu, zamiast zostać zaakceptowany i po cichu zawieść później z mylącym błędem gateway.
Jeśli intent zostanie wyłączony po tym, jak bot już działa (załóżmy, że ktoś odznaczy go w portalu miesiące później), gateway Discorda zamyka połączenie kodami 4013 lub 4014. Węzły hostingowe Noxyr wychwytują ten konkretny kod zamknięcia, wyłączają bota i publikują zrozumiały komunikat o statusie, który dokładnie mówi, którego ustawienia naprawić, zamiast zostawiać go w cichej pętli ponownych połączeń. Pełny opis tego błędu i innych częstych przyczyn trybu offline znajdziesz w naszym przewodniku po rozwiązywaniu błędów gateway 4004/4014.
Najczęstsze pytania
Czy do Bota niestandardowego Noxyr potrzebuję Presence Intent? Nie. Noxyr żąda tylko Server Members Intent i Message Content Intent. Presence Intent może pozostać wyłączony.
Dlaczego mój bot pokazuje „disallowed intents”, mimo że włączyłem przełączniki? Gateway odczytuje aktualny stan tylko przy świeżym logowaniu. Zrestartuj bota po zapisaniu ustawień w portalu, aby połączył się ponownie z zastosowanymi nowymi intentami.
Czy włączenie Message Content Intent oznacza, że Discord udostępnia botowi historię wiadomości? Nie. Dotyczy to tylko wiadomości wysyłanych, gdy bot jest połączony i ma dostęp do danego kanału. Nie przyznaje wstecznie dostępu do dawnych wiadomości, przy których bot nie był obecny.
Czy mój bot zostanie zbanowany za żądanie uprzywilejowanych intentów? Nie. Żądanie ich i używanie do funkcji, które ich wymagają - wiadomości powitalne, autoresponderów, odpowiedzi AI - jest dokładnie ich przeznaczeniem. Weryfikacja dotyczy botów na dużą skalę, a nie jest karą.
Pełny opis konfiguracji znajdziesz w dokumentacji Bota niestandardowego, albo dodaj Noxyr za darmo i w ogóle pomiń intenty, uruchamiając główny bot zamiast niestandardowego opartego na tokenie.