Como Usar Intents do Bot do Discord Corretamente em Python

Ao criar um bot do Discord em Python, você pode notar que alguns eventos nunca são acionados. Seu bot pode não ver entradas de membros, conteúdo de mensagens ou atualizações de presença. Isso acontece porque o Discord exige permissões explícitas chamadas intents. Sem ativar as intents corretas, seu bot perde dados importantes. Este artigo explica o que são intents, por que existem e como configurá-las corretamente em Python usando a biblioteca discord.py.

O Que São Intents do Bot do Discord e Por Que Elas Importam

Intents são flags de permissão que informam ao Discord quais eventos seu bot deseja receber. O Discord introduziu intents em 2020 para reduzir dados desnecessários enviados aos bots. Antes das intents, todo bot recebia todos os eventos, mesmo que não precisasse. Isso causava problemas de desempenho para bots grandes e preocupações com privacidade para membros do servidor.

Existem três intents privilegiadas que exigem ativação explícita:

Intent de Membros do Servidor

Esta intent permite que seu bot receba eventos on_member_join, on_member_remove e on_member_update. Sem ela, seu bot não consegue ver quando alguém entra ou sai de um servidor. Se seu bot gerencia mensagens de boas-vindas ou atribuições de cargos, você precisa desta intent.

Intent de Conteúdo de Mensagem

Esta intent permite que seu bot leia o conteúdo textual das mensagens. Sem ela, seu bot ainda pode receber eventos de mensagem, mas o campo message.content estará vazio. Esta intent é necessária para qualquer bot que analise comandos ou filtre texto. O Discord tornou esta intent privilegiada para proteger a privacidade do usuário e reduzir spam.

Intent de Presença

Esta intent permite que seu bot veja atualizações de status dos membros, como online, ausente ou não perturbe. Também inclui texto de status personalizado e atividade de jogo. A maioria dos bots não precisa desta intent, a menos que monitore disponibilidade ou exiba recursos avançados de presença.

Intents não privilegiadas, como guilds, messages (sem conteúdo) e voice_states, são ativadas por padrão. Você só precisa ativar manualmente as privilegiadas.

Passos para Ativar Intents do Bot em Python com discord.py

Siga estes passos para configurar intents para seu bot do Discord. Você precisará de uma aplicação Discord já criada no Portal do Desenvolvedor Discord e Python 3.8 ou superior instalado.

1. Ative as intents no Portal do Desenvolvedor Discord
   Acesse https://discord.com/developers/applications. Selecione sua aplicação de bot. No menu à esquerda, clique em Bot. Role até Intents de Gateway Privilegiadas. Ative as intents de Membros do Servidor, Conteúdo de Mensagem e Presença conforme necessário. Clique em Salvar Alterações.
2. Instale ou atualize o discord.py
   Abra um terminal. Execute pip install -U discord.py. Isso garante que você tenha a versão mais recente com suporte completo a intents.
3. Crie um objeto de intents no seu código Python
   Importe o discord. Crie um objeto de intents. Use discord.Intents.default() para começar com intents padrão não privilegiadas e depois ative as específicas. Exemplo:
   intents = discord.Intents.default()
intents.members = True
intents.message_content = True
intents.presences = True
4. Passe o objeto de intents para seu cliente
   Ao criar seu cliente de bot, inclua o parâmetro intents:
   client = discord.Client(intents=intents)
   Se você usa commands.Bot, faça o mesmo:
   bot = commands.Bot(command_prefix='!', intents=intents)
5. Teste seu bot
   Execute seu script do bot. Verifique se eventos como on_member_join são acionados corretamente. Imprima o conteúdo da mensagem em on_message para confirmar que a Intent de Conteúdo de Mensagem funciona.

Alternativa: Use discord.Intents.all()

Se você quiser todas as intents possíveis ativadas, use intents = discord.Intents.all(). Isso é conveniente para testes, mas não recomendado para produção. Intents desnecessárias aumentam o uso de memória e a sobrecarga de processamento de eventos.

Erros Comuns ao Usar Intents do Bot

O Bot Não Recebe Eventos de Entrada de Membros

A causa mais comum é a Intent de Membros do Servidor não ativada no Portal do Desenvolvedor. Mesmo que você defina intents.members = True no código, a configuração do portal a substitui. Verifique novamente se a opção está ativada. Certifique-se também de que seu bot tenha a intent guilds, que é ativada por padrão com discord.Intents.default().

Conteúdo da Mensagem Está Vazio em on_message

Se message.content retornar uma string vazia, a Intent de Conteúdo de Mensagem está faltando. Ative-a no Portal do Desenvolvedor e defina intents.message_content = True no seu código. Observe que mensagens de outros bots ainda terão conteúdo vazio por questões de privacidade.

O Bot Aparece Offline ou Não Responde

Isso geralmente não é um problema de intents. Verifique seu token do bot, conexão com a internet e se seu script Python é executado sem erros. Intents não afetam a conectividade básica.

Eventos de Presença Não São Acionados

Ative a Intent de Presença no Portal do Desenvolvedor e defina intents.presences = True. Defina também intents.members = True, pois atualizações de presença geralmente estão vinculadas a objetos de membro. Sem ambos, você pode ver dados incompletos.

Níveis de Intent do Bot do Discord: Padrão vs Privilegiada

Tipo de Intent	Padrão (não privilegiada)	Privilegiada (requer ativação no portal)
guilds	Sim	Não
messages (sem conteúdo)	Sim	Não
voice_states	Sim	Não
message_content	Não	Sim
members	Não	Sim
presences	Não	Sim

Intents não privilegiadas são seguras para ativar em qualquer bot. Intents privilegiadas exigem aprovação do Discord se seu bot estiver em mais de 100 servidores. Para bots menores, você pode ativá-las livremente no Portal do Desenvolvedor.

Agora você pode configurar intents do bot do Discord corretamente em Python. Comece ativando apenas as intents que seu bot realmente precisa. Para um bot de moderação, ative Conteúdo de Mensagem e Membros do Servidor. Para um bot de música, você pode precisar apenas das intents padrão mais voice_states. Use discord.Intents.default() como base e adicione flags específicas. Essa abordagem mantém seu bot eficiente e em conformidade com as diretrizes de privacidade do Discord.