Gli intent privilegiati del gateway Discord sono tre permessi da attivare esplicitamente (Presence, Server Members e Message Content) che il proprietario di un bot deve abilitare nel Portale per sviluppatori prima che Discord invii quei dati tramite il gateway. Esistono perché le liste dei membri e il testo dei messaggi sono sensibili per impostazione predefinita. Se ne manchi uno, il bot non dà un errore evidente: smette semplicemente di ricevere gli eventi di cui ha bisogno, ed è per questo che «il mio bot è online ma non fa nulla» finisce così spesso per dipendere da un interruttore di intent.
Cos'è davvero un intent del gateway
Quando un bot si connette a Discord, non riceve automaticamente ogni evento che accade in ogni server in cui si trova. Si iscrive a categorie di eventi chiamate intent: eventi dei messaggi, eventi dello stato vocale, eventi di aggiornamento del server e così via. La maggior parte degli intent si dichiara liberamente nel codice e Discord li concede senza chiedere nulla. Tre sono diversi. Discord li chiama intent privilegiati perché i dati che si nascondono dietro, esattamente chi è in un server e cosa stanno scrivendo i membri, sono abbastanza potenti da richiedere che il proprietario del bot li abiliti esplicitamente nel Portale per sviluppatori, non solo nel codice.
Se il codice di un bot richiede un intent privilegiato ma il proprietario non l'ha attivato per quell'applicazione, Discord rifiuta del tutto il login. Il bot non va online in uno stato degradato: non si connette affatto, e il gateway si chiude con un errore «disallowed intents».
I tre intent privilegiati
- Presence Intent. Stato online/inattivo/offline e attività personalizzate di ogni membro. Usato dai bot che mostrano dati di presenza in tempo reale; la maggior parte dei bot per ticket, moderazione e commercio, Noxyr compreso, non ne ha bisogno.
- Server Members Intent. La lista completa dei membri, più gli eventi di ingresso e uscita, i cambi di ruolo e gli aggiornamenti dei soprannomi. È l'intent alla base dei messaggi di benvenuto, dei conteggi dei membri e del rilevamento anti-raid.
- Message Content Intent. Il testo effettivo di un messaggio, non solo il fatto che un messaggio sia stato inviato. Senza di esso, un bot può vedere che qualcuno ha scritto in un canale ma non cosa ha digitato.
Il codice di Noxyr richiede due dei tre: Server Members Intent e Message Content Intent. Presence Intent non fa parte di nessuna funzione di Noxyr, quindi non viene mai richiesto e non va mai attivato.
Cosa si rompe senza Server Members Intent
Server Members Intent è ciò che permette a un bot di ricevere gli eventi GUILD_MEMBER_ADD e GUILD_MEMBER_REMOVE, gli eventi di ingresso e uscita da cui dipende quasi ogni funzione legata ai membri.
- Messaggi di benvenuto. Un messaggio di benvenuto parte all'ingresso. Senza l'intent, il bot non riceve mai l'evento di ingresso, quindi non viene pubblicato nulla e non viene assegnato alcun ruolo automatico.
- Conteggio dei membri. Un canale o un widget con il conteggio dei membri in tempo reale si aggiorna con gli stessi eventi di ingresso e uscita. Senza l'intent si blocca al conteggio che ha visto per ultimo.
- Anti-nuke e protezione dai raid. Rilevare un raid di ingressi di massa o controllare cambi sospetti di ruolo e soprannome dipende dagli eventi dei membri. Se disattivi l'intent, l'intero percorso di rilevamento si spegne.
- Flussi di verifica. Qualsiasi controllo che verifichi la data di ingresso, i ruoli o l'età dell'account di un membro ha bisogno dell'oggetto membro fornito dall'intent.
Cosa si rompe senza Message Content Intent
Message Content Intent regola l'accesso al testo effettivo di un messaggio. Un bot può ancora vedere che un canale ha ricevuto un messaggio e chi l'ha inviato senza questo intent; semplicemente non può leggere cosa è stato detto.
- Risposte automatiche. Riconoscere una parola trigger come «rimborso» o «come pago» richiede di leggere il testo del messaggio. Senza contenuto, nessuna corrispondenza, nessuna risposta.
- Risposte della chat AI. Un assistente AI che risponde alle domande in un canale o quando viene menzionato ha bisogno della domanda stessa. Senza l'intent sa che qualcuno ha parlato ma non ha nulla da inviare al modello.
- Trascrizioni dei ticket. Una trascrizione che registra ciò che lo staff e i membri hanno detto davvero in un ticket ha bisogno del contenuto dei messaggi; senza, otterresti un elenco di orari e nomi utente senza alcun contenuto.
- Moderazione basata sui prefissi. Qualsiasi cosa che controlli i messaggi per parole vietate, link di invito o schemi di spam legge il contenuto esattamente come fa una risposta automatica.
I comandi slash non ne risentono in nessun caso, perché Discord consegna l'input dei comandi separatamente dai messaggi normali. Sono specificamente le funzioni che leggono ciò che i membri scrivono nei messaggi ordinari a dipendere da questo intent.
Come attivare gli intent nel Portale per sviluppatori
- Apri il Portale per sviluppatori Discord e seleziona l'applicazione del bot.
- Clicca Bot nella barra laterale sinistra.
- Scorri fino a Privileged Gateway Intents.
- Attiva Server Members Intent e Message Content Intent (aggiungi Presence Intent solo se un bot ha specificamente bisogno dei dati di stato in tempo reale).
- Salva le modifiche, poi riavvia o riconnetti il bot così al login successivo applica i nuovi intent.
L'interruttore ha effetto alla connessione successiva al gateway, non immediatamente per un bot già autenticato. Un bot che era in sessione quando un intent è stato disattivato di solito viene disconnesso da Discord e deve essere riconnesso una volta riattivato l'intent.
La regola di verifica dei 100 server
Attivare l'interruttore nel portale basta per un bot in meno di 100 server. Quando il numero di installazioni di un bot supera i 100 server, Discord richiede che l'applicazione superi la verifica del bot, un processo di revisione in cui il proprietario invia il bot per l'approvazione, prima di potere usare intent privilegiati su quella scala. Un bot non verificato che raggiunge la soglia continua a funzionare nei server in cui è già presente, ma viene limitato dall'entrare in nuovi server finché la verifica non viene concessa o finché non vengono rimossi gli intent privilegiati di cui non ha strettamente bisogno.
Questa è una regola della piattaforma Discord, non qualcosa che controlla un singolo host di bot. Esiste perché intent sensibili come Server Members e Message Content non vengano distribuiti su larga scala senza la revisione di Discord su ciò che il bot ne fa.
Perché Noxyr controlla entrambi gli intent prima di accettare un token
La funzione Custom Bot di Noxyr esegue l'intero set di funzioni con un token del bot fornito da te. Poiché messaggi di benvenuto, conteggi dei membri, chat AI, trascrizioni dei ticket e risposte automatiche dipendono entrambi dai due intent sopra, la dashboard verifica che Server Members Intent e Message Content Intent siano attivi prima di accettare il tuo token. Un token incollato con uno dei due disattivato viene rifiutato subito, invece di essere accettato e lasciato fallire in silenzio più tardi con un confuso errore del gateway.
Se un intent viene disattivato dopo che il bot è già in funzione (per esempio, qualcuno lo deseleziona nel portale mesi dopo), il gateway di Discord chiude la connessione con i codici 4013 o 4014. I nodi di hosting di Noxyr intercettano quello specifico codice di chiusura, spengono il bot e pubblicano un messaggio di stato in linguaggio semplice che indica esattamente quale impostazione correggere, invece di lasciarlo bloccato in un ciclo di riconnessione silenzioso. La spiegazione completa di quell'errore e delle altre cause comuni di offline si trova nella nostra guida alla risoluzione dell'errore gateway 4004/4014.
Domande frequenti
Mi serve Presence Intent per il Custom Bot di Noxyr? No. Noxyr richiede solo Server Members Intent e Message Content Intent. Presence Intent può restare disattivato.
Perché il mio bot mostra «disallowed intents» anche se ho attivato gli interruttori? Il gateway legge lo stato attuale solo a un nuovo login. Riavvia il bot dopo aver salvato le impostazioni del portale, così si riconnette con i nuovi intent applicati.
Attivare Message Content Intent significa che Discord condivide con il bot la cronologia dei messaggi? No. Riguarda solo i messaggi inviati mentre il bot è connesso e ha accesso a quel canale. Non concede retroattivamente l'accesso ai messaggi passati a cui il bot non era presente.
Il mio bot verrà bannato per aver richiesto intent privilegiati? No. Richiederli e usarli per le funzioni che ne hanno bisogno, messaggi di benvenuto, risposte automatiche, risposte AI, è esattamente il loro scopo. La verifica esiste per i bot su larga scala, non come punizione.
Trovi la guida completa alla configurazione nella documentazione dei Custom Bot, oppure aggiungi Noxyr gratis ed evita del tutto gli intent usando il bot principale invece di un bot personalizzato basato su token.