Um link de convite de bot do Discord é apenas uma URL de autorização OAuth2: o parâmetro de escopo decide que tipo de acesso está sendo solicitado (uma conta de bot, comandos de barra, ou ambos), e o número de permissões decide o que essa conta de bot pode fazer depois de entrar; além disso, um admin do servidor precisa aprovar tudo antes que qualquer coisa tenha efeito. Entender esses dois parâmetros é a diferença entre criar um link de convite seguro e copiar um que você não consegue explicar por completo.
Anatomia de um link de convite
Um convite típico de bot tem esta aparência:
https://discord.com/oauth2/authorize?client_id=123456789&permissions=268446800&scope=bot%20applications.commands
- client_id - o ID público da aplicação, seguro para compartilhar; ele aparece em todo link de convite daquele bot.
- scope - que tipo de acesso está sendo solicitado, separado por espaços (codificado na URL como
%20). - permissions - um único número que representa cada permissão de servidor solicitada, somadas.
- guild_id e disable_guild_select (opcionais) - pré-selecionam um servidor específico e travam o seletor nele, útil para um botão "me adicione aqui" por servidor.
O escopo "bot"
É isso que realmente adiciona o bot como membro do servidor, a entrada que aparece na lista de membros com a etiqueta de bot ao lado. Sem esse escopo, nada entra; não há conta de bot para autorizar.
O escopo "applications.commands"
Este registra os comandos de barra, de usuário e de mensagem da aplicação para que possam ser usados naquele servidor. Tecnicamente, um bot pode entrar apenas com o escopo bot, mas nenhum dos seus /commands aparecerá quando alguém digitar /, porque o servidor nunca autorizou o registro de comandos.
Por que você quase sempre quer os dois
Um bot convidado apenas com bot ainda pode enviar mensagens, reagir a botões nas mensagens que já enviou e responder a coisas que não exigem um comando de barra. Mas usuários modernos do Discord esperam comandos, e um bot que não consegue registrá-los parece quebrado, mesmo quando está funcionando perfeitamente. Todo link de convite gerado pela Noxyr, e quase todo link de bot legítimo, inclui os dois escopos juntos justamente por isso.
O número de permissões, decodificado
Cada permissão do Discord, enviar mensagens, gerenciar cargos, expulsar membros, é um único bit em um campo de bits: uma flag de potência de dois. O número no link de convite é a soma de todas as flags solicitadas de uma vez. Um link que pede permissions igual a 8 está pedindo exatamente uma coisa: Administrador, acesso total e irrestrito ao servidor. Um link de convite bem construído soma apenas as flags específicas que o código do bot realmente usa: gerenciamento de canais para criar canais de ticket, gerenciamento de cargos para um cargo de verificação, ações de moderação para resposta a raids, e não tudo o que o Discord disponibiliza.
Por que Administrador é um sinal de alerta, não uma exigência
A maioria dos bots legítimos não precisa dele. Pedi-lo é, ou uma necessidade genuína e rara de algo que toca quase todas as permissões ao mesmo tempo, ou, com muito mais frequência, um bot construído às pressas com permissions igual a 8 colado porque era o número mais fácil de alcançar. É também a tela mais assustadora que o Discord mostra ao dono do servidor durante a configuração, o que faz dele um motivo comum para um convite ser recusado logo de cara ou para o bot ser removido depois por alguém que está arrumando as permissões. Você pode decodificar o número de permissões de qualquer link de convite com uma calculadora de permissões do Discord antes de clicar em Autorizar, para ver exatamente o que está sendo pedido.
Como o link de convite da Noxyr é construído, como exemplo
Em vez de pedir Administrador, o convite da Noxyr é montado com as permissões específicas que os seus recursos realmente usam: gerenciamento de canais e cargos para tickets e verificação, permissões de mensagem e moderação para respostas do anti-nuke, e nada além dessa lista. Ele sempre inclui os escopos bot e applications.commands, então os seus comandos funcionam no momento em que ele entra.
Outros escopos OAuth2 que você verá mencionados
O Discord define dezenas de escopos OAuth2 além de bot e applications.commands; a maioria deles, como identify ou guilds.join, pertence à autenticação web no estilo "Entrar com o Discord", e não aos convites de bot, e não aparece de jeito nenhum em um link de convite padrão. Se um link que você está vendo pede algo estranho junto com bot, vale verificar o que esse escopo realmente concede antes de autorizar, já que um convite de bot precisar legitimamente de escopos extras de autenticação web é incomum, fora de um serviço que também oferece vinculação de contas.
Criando o link de convite do seu próprio bot personalizado
Depois de criar uma aplicação no Portal de Desenvolvedores do Discord, o Gerador de URL da aba OAuth2 monta esse link para você por meio de caixas de seleção: marque bot e applications.commands em escopos, marque as permissões de que o seu bot precisa e copie o resultado, em vez de montar a URL e o número de permissões manualmente.
Perguntas frequentes
O que faz o disable_guild_select? Ele trava o seletor de servidores em um único servidor pré-escolhido, então um link de convite destinado a uma comunidade específica não pode ser usado por acidente para adicionar o bot em outro lugar.
Preciso de applications.commands se o meu bot usa apenas botões? Não estritamente para botões em mensagens que ele já enviou, mas você precisa dele no momento em que qualquer comando de barra estiver envolvido.
Alterar o número de permissões depois pode adicionar acesso retroativamente? Não. Um servidor que já aprovou um convite mantém o que foi concedido naquele momento; alterar o link afeta apenas convites futuros, e as instalações existentes precisam ser convidadas e aprovadas de novo para ganhar mais.
Só scope=bot basta? Basta para o bot entrar, mas os comandos de barra dele não aparecerão sem applications.commands junto.
Por que o Discord mostra um aviso tão grande para Administrador? Porque ele pede acesso irrestrito ao servidor inteiro, a permissão mais perigosa que um convite de bot pode solicitar.
Configurando o convite do seu próprio bot? Veja antes o nosso guia de criação de uma aplicação do Discord, depois leia a documentação do Bot Personalizado se preferir não precisar escrever o código por trás dele.