Como Usar Conexões de Cargos do Discord com Contas Vinculadas via OAuth2

As Conexões de Cargos do Discord permitem que membros do servidor vinculem contas externas como YouTube, Twitter ou Steam ao perfil do Discord. Uma vez vinculadas, você pode atribuir cargos automaticamente com base nessas contas usando OAuth2. Esse recurso ajuda a verificar a identidade de um membro ou conceder acesso a canais exclusivos com base no status da conta externa. Neste artigo, você aprenderá a configurar um aplicativo Discord, definir escopos OAuth2 para conexões de cargos e criar a lógica de atribuição de cargos que funcione com os cargos do seu servidor.

O Que São Conexões de Cargos do Discord e Como o OAuth2 Vincula Contas

As Conexões de Cargos do Discord permitem que um usuário vincule uma conta externa, como um canal do YouTube, perfil do Twitter ou Steam, diretamente ao perfil do Discord. Quando o vínculo é estabelecido, o perfil do usuário no Discord exibe um pequeno selo mostrando a conta vinculada. Os proprietários de servidores podem criar cargos que são atribuídos automaticamente com base nos metadados dessa conta vinculada. Por exemplo, você pode atribuir um cargo chamado “Inscrito no YouTube” a qualquer membro que vincule um canal do YouTube com pelo menos 100 inscritos.

O fluxo OAuth2 é o mecanismo que torna isso possível. Seu aplicativo Discord solicita permissão ao usuário para ler os dados da conta externa e escrever metadados de conexão de cargo. O usuário autoriza seu aplicativo, e seu aplicativo então define um objeto de metadados no perfil do usuário no Discord. Os servidores do Discord verificam esses metadados em relação às regras de atribuição de cargos que você configurou no servidor. Se os metadados corresponderem às condições definidas, o cargo é concedido ou revogado automaticamente.

Pré-requisitos para Usar Conexões de Cargos

Antes de começar, você precisa do seguinte:

• Um servidor Discord onde você tenha a permissão Gerenciar Servidor.
• Um aplicativo Discord criado no Portal do Desenvolvedor Discord.
• Acesso à API da plataforma externa (por exemplo, YouTube Data API ou Twitter API v2) para buscar os dados da conta do usuário.
• Um servidor backend capaz de lidar com redirecionamentos OAuth2 e fazer requisições HTTP à API do Discord.

Passos para Configurar Conexões de Cargos do Discord com OAuth2

O processo envolve quatro etapas principais: configurar seu aplicativo Discord, construir a URL de autorização OAuth2, lidar com o callback para buscar os dados da conta externa e atualizar os metadados da conexão de cargo. Siga estes passos em ordem.

1. Crie ou selecione seu aplicativo Discord no Portal do Desenvolvedor
   Acesse o Portal do Desenvolvedor Discord e clique em New Application. Dê um nome ao seu aplicativo e clique em Create. Se você já tem um aplicativo, selecione-o na lista.
2. Ative as conexões de cargos e adicione os escopos OAuth2 necessários
   Nas configurações do seu aplicativo, clique em OAuth2 na barra lateral esquerda. Em Scopes, selecione role_connections.write. Esse escopo permite que seu aplicativo escreva metadados de conexão de cargo no perfil do usuário. Adicione também os escopos apropriados para a plataforma externa: para YouTube, adicione youtube.readonly; para Twitter, adicione tweet.read e users.read. Clique em Save Changes.
3. Construa a URL de autorização OAuth2
   Use o modelo a seguir para construir a URL que os usuários clicarão para vincular sua conta. Substitua YOUR_CLIENT_ID pelo ID do cliente do seu aplicativo e YOUR_REDIRECT_URI pela URL para onde os usuários serão enviados após a autorização.
   https://discord.com/api/oauth2/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&scope=role_connections.write%20identify
   Você deve incluir o escopo identify para ler o ID do usuário no Discord. Se precisar de dados da plataforma externa, adicione o escopo dela à URL também, separado por %20.
4. Lide com o callback OAuth2 e troque o código por um token de acesso
   Quando o usuário autorizar seu aplicativo, o Discord o redireciona para sua URI de redirecionamento com um parâmetro de consulta code. Seu servidor backend deve trocar esse código por um token de acesso fazendo uma requisição POST para https://discord.com/api/oauth2/token com os seguintes parâmetros:
   client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=authorization_code&code=THE_CODE&redirect_uri=YOUR_REDIRECT_URI
   A resposta contém um access_token que você usará para chamadas subsequentes à API.
5. Busque os dados da conta externa do usuário
   Use o token de acesso para chamar a API da plataforma externa. Por exemplo, para obter os dados do canal do YouTube do usuário, chame https://www.googleapis.com/youtube/v3/channels?part=statistics&mine=true com o token no cabeçalho Authorization. Extraia os metadados relevantes, como número de inscritos ou nome do canal.
6. Atualize os metadados da conexão de cargo no Discord
   Faça uma requisição PUT para https://discord.com/api/v10/users/@me/applications/YOUR_APPLICATION_ID/role-connection. Inclua o cabeçalho Authorization: Bearer ACCESS_TOKEN. O corpo da requisição é um objeto JSON onde o campo metadata contém pares chave-valor que você define. Exemplo de corpo:
   {"platform_name": "YouTube", "metadata": {"subscriber_count": "150", "channel_name": "MyChannel"}}
   As chaves que você usa no objeto metadata devem corresponder aos nomes que você usará posteriormente na configuração de atribuição de cargos do servidor.
7. Configure a atribuição de cargos no seu servidor Discord
   Abra seu servidor Discord e vá para Configurações do Servidor > Cargos. Crie um novo cargo ou edite um existente. Em Conexões de Cargos, clique em Adicionar Requisito. Selecione a plataforma que você vinculou (por exemplo, YouTube) e defina a condição. Por exemplo, defina Número de Inscritos como maior ou igual a 100. O Discord atribuirá automaticamente esse cargo a qualquer membro cujos metadados da conexão de cargo atendam à condição.
8. Teste o fluxo com uma conta de usuário
   Use uma conta de teste do Discord que não seja o proprietário do servidor. Faça com que esse usuário clique na URL de autorização OAuth2 que você construiu. Após a autorização, verifique o perfil do Discord para confirmar que o selo da conta vinculada aparece. Em seguida, verifique se o cargo foi atribuído automaticamente no servidor.

Erros Comuns e Limitações ao Usar Conexões de Cargos

O cargo não é atribuído após o usuário vincular a conta

O motivo mais comum é que os metadados que você escreveu no Discord não correspondem à condição definida no requisito do cargo. Verifique novamente os nomes exatos das chaves e os tipos de dados. Por exemplo, se você escreveu "subscriber_count": "150" como string, mas o requisito do cargo espera um inteiro, a comparação pode falhar. Use o tipo de dados correto conforme definido pela API da plataforma.

A autorização OAuth2 falha com erro de escopo inválido

Isso acontece quando você solicita um escopo que seu aplicativo não recebeu no Portal do Desenvolvedor. Verifique se você adicionou o escopo role_connections.write e quaisquer escopos de plataforma externa em OAuth2 > Scopes nas configurações do seu aplicativo. Confirme também se sua URI de redirecionamento é exatamente a mesma registrada no portal.

Os metadados da conexão de cargo não persistem após o usuário sair

Os metadados da conexão de cargo que você escreve estão vinculados ao perfil do usuário no Discord e persistem até que você os exclua ou o usuário revogue a autorização. Se os dados desaparecerem, seu backend pode não estar armazenando o token de acesso de forma segura. Você precisa armazenar o token de atualização do usuário e usá-lo para obter um novo token de acesso quando o antigo expirar. Os tokens OAuth2 do Discord para conexões de cargos têm uma vida útil mais longa, mas você ainda deve implementar a lógica de renovação de token.

Você não pode atribuir cargos com base em metadados de várias plataformas em uma única condição

Cada requisito de cargo só pode verificar metadados de uma única plataforma. Para exigir tanto uma inscrição no YouTube quanto um seguidor no Twitter, você precisaria criar dois cargos separados. Alternativamente, você pode escrever metadados de ambas as plataformas em um único objeto de conexão de cargo, mas o Discord só avalia as condições para a plataforma que você selecionar no menu suspenso de requisitos.

Item	OAuth2 com Conexões de Cargos	Atribuição Manual de Cargos
Complexidade de configuração	Requer um servidor backend e configuração no Portal do Desenvolvedor	Nenhuma programação necessária, apenas configurações do servidor
Automação	Cargos são atribuídos instantaneamente após a autorização	Cargos devem ser atribuídos manualmente por um administrador
Verificação	Usa dados reais da conta externa da API da plataforma	Depende do julgamento do administrador ou verificações manuais
Escalabilidade	Funciona para centenas de usuários sem trabalho adicional	Torna-se demorado à medida que o servidor cresce

Agora você pode configurar Conexões de Cargos do Discord com OAuth2 para atribuir cargos automaticamente com base em contas externas vinculadas. Comece criando seu aplicativo no Portal do Desenvolvedor e construindo a URL de autorização. Depois que o fluxo estiver funcionando, teste com alguns usuários para garantir que as condições dos metadados correspondam aos requisitos do cargo. Para uso avançado, considere armazenar o token de atualização do usuário em um banco de dados para que você possa atualizar periodicamente os metadados da conexão de cargo sem exigir nova autorização.