Un link di invito per un bot Discord è solo un URL di autorizzazione OAuth2: il suo parametro scope decide che tipo di accesso viene richiesto (un account bot, i comandi slash o entrambi), mentre il suo numero di permessi decide cosa può fare quell'account bot una volta entrato; inoltre un amministratore del server deve approvare l'intera richiesta prima che qualsiasi cosa abbia effetto. Capire questi due parametri fa la differenza tra costruire un link di invito sicuro e copiarne uno di cui non sai spiegare fino in fondo il contenuto.
Anatomia di un link di invito
Un invito tipico per un bot ha questo aspetto:
https://discord.com/oauth2/authorize?client_id=123456789&permissions=268446800&scope=bot%20applications.commands
- client_id - l'ID pubblico dell'applicazione, sicuro da condividere: è presente in ogni link di invito di quel bot.
- scope - il tipo di accesso richiesto, separato da spazi (codificato nell'URL come
%20). - permissions - un singolo numero che rappresenta tutti i permessi del server richiesti, sommati tra loro.
- guild_id e disable_guild_select (facoltativi) - preselezionano un server specifico e bloccano il selettore su di esso, utile per un pulsante «aggiungimi qui» su ogni server.
Lo scope «bot»
È questo che aggiunge davvero il bot come membro del server, la voce che compare nell'elenco dei membri con l'etichetta BOT accanto. Senza questo scope non entra nulla: non c'è nessun account bot da autorizzare.
Lo scope «applications.commands»
Questo scope registra i comandi slash, utente e messaggio dell'applicazione, così possono essere usati in quel server. Tecnicamente un bot può entrare anche solo con lo scope bot, ma nessuno dei suoi /comandi comparirà quando qualcuno digita /, perché il server non ha autorizzato la registrazione dei comandi.
Perché di solito servono entrambi
Un bot invitato solo con bot può ancora pubblicare messaggi, reagire ai pulsanti sui messaggi che ha già inviato e rispondere a cose che non richiedono un comando slash. Ma gli utenti Discord moderni si aspettano i comandi, e un bot che non riesce a registrarli sembra rotto anche quando funziona perfettamente. Per questo motivo ogni link di invito generato da Noxyr, e quasi ogni bot legittimo, include entrambi gli scope insieme.
Il numero dei permessi, spiegato
Ogni permesso di Discord, inviare messaggi, gestire i ruoli, espellere membri, è un singolo bit in un campo di bit: un flag che è una potenza di due. Il numero nel link di invito è la somma di tutti i flag richiesti contemporaneamente. Un link che chiede permissions uguale a 8 sta chiedendo esattamente una cosa: Amministratore, cioè accesso completo e senza restrizioni al server. Un link di invito ben costruito somma invece solo i permessi specifici che il codice del bot usa davvero: gestione dei canali per creare i canali dei ticket, gestione dei ruoli per un ruolo di verifica, azioni di moderazione per la risposta anti-raid, non tutto ciò che Discord mette a disposizione.
Perché Amministratore è un campanello d'allarme, non un requisito
La maggior parte dei bot legittimi non ne ha bisogno. Chiederlo è o un'esigenza reale ma rara, per qualcosa che tocca quasi tutti i permessi insieme, oppure, molto più spesso, un bot costruito in fretta con permissions uguale a 8 incollato perché era il numero più facile da trovare. È anche la schermata più inquietante che Discord mostra al proprietario del server durante la configurazione, il che la rende un motivo comune per cui un invito viene rifiutato del tutto o il bot viene rimosso in seguito da qualcuno che sistema i permessi. Puoi decodificare il numero dei permessi di qualsiasi link di invito con un calcolatore di permessi Discord prima di cliccare su Autorizza, per vedere esattamente cosa viene richiesto.
Come è costruito il link di invito di Noxyr, come esempio
Invece di richiedere Amministratore, l'invito di Noxyr è costruito a partire dai permessi specifici che le sue funzionalità usano davvero: gestione dei canali e dei ruoli per ticket e verifica, permessi di messaggi e moderazione per le risposte anti-nuke, e nient'altro oltre questo elenco. Include sempre sia lo scope bot sia applications.commands, così i suoi comandi funzionano nel momento in cui entra.
Altri scope OAuth2 che potresti incontrare
Discord definisce decine di scope OAuth2 oltre a bot e applications.commands. La maggior parte, come identify o guilds.join, appartiene all'autenticazione web in stile «Accedi con Discord» e non compare affatto in un link di invito standard. Se un link che stai guardando richiede qualcosa di sconosciuto insieme a bot, vale la pena verificare cosa concede davvero quello scope prima di autorizzarlo, perché un invito per un bot che ha bisogno di scope di autenticazione web aggiuntivi è insolito, a meno che non si tratti di un servizio che offre anche il collegamento di account.
Costruire il link di invito del tuo bot personalizzato
Una volta creata un'applicazione nel Portale per sviluppatori Discord, lo strumento URL Generator della scheda OAuth2 costruisce questo link per te con delle caselle: seleziona bot e applications.commands tra gli scope, seleziona i permessi di cui il bot ha bisogno e copia il risultato, invece di assemblare a mano l'URL e il numero dei permessi.
Domande frequenti
Cosa fa disable_guild_select? Blocca il selettore dei server su un unico server preselezionato, così un link di invito pensato per una specifica community non può essere usato per aggiungere il bot da qualche altra parte per sbaglio.
Mi serve applications.commands se il mio bot usa solo i pulsanti? Non strettamente per i pulsanti sui messaggi che ha già inviato, ma ti serve nel momento in cui è coinvolto un comando slash.
Cambiare il numero dei permessi più tardi può aggiungere accessi in modo retroattivo? No. Un server che ha già approvato un invito mantiene ciò che è stato concesso in quel momento; cambiare il link influisce solo sugli inviti futuri, e le installazioni esistenti devono essere reinvitate e riapprovate per ottenere di più.
scope=bot basta da solo? Basta perché il bot entri, ma i suoi comandi slash non compariranno senza applications.commands insieme a esso.
Perché Discord mostra un avviso così grande per Amministratore? Perché chiede accesso senza restrizioni all'intero server, il permesso più pericoloso che un invito per un bot possa richiedere.
Stai configurando l'invito del tuo bot? Leggi prima la nostra guida su come creare un'applicazione Discord, poi la documentazione sui bot personalizzati se preferisci evitare di scrivere da zero il codice che ci sta dietro.