Como Criar um Bot do Discord com Comandos de Barra Usando discord.py 2.0

Você quer criar um bot do Discord que use comandos de barra em vez dos tradicionais comandos baseados em prefixo. Comandos de barra aparecem na interface do usuário e oferecem preenchimento automático, opções obrigatórias e controles de permissão. Este artigo mostra como construir um bot básico com Python 3.8 ou superior usando a biblioteca discord.py 2.0. Você aprenderá a configurar seu token de bot, escrever um grupo de comandos e implantar o bot em um servidor.

O que é discord.py 2.0 e como funcionam os comandos de barra

discord.py 2.0 é uma grande atualização da popular biblioteca Python para interagir com a API do Discord. A biblioteca agora suporta Application Commands, que incluem comandos de barra, comandos de menu de contexto de usuário e comandos de menu de contexto de mensagem. Comandos de barra são comandos que os usuários digitam com uma barra e são definidos no código, em vez de serem analisados a partir de um prefixo de mensagem como ! ou ..

Quando um usuário digita um comando de barra, o Discord envia um evento de interação para o seu bot. Seu bot recebe a interação, processa e responde em até três segundos. Para processamento mais longo, você pode adiar a resposta e depois enviar um follow-up. O módulo discord.app_commands lida automaticamente com a análise de opções, preenchimento automático e verificação de permissões.

Pré-requisitos para este tutorial

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

• Python 3.8 ou superior instalado no seu computador
• Uma conta do Discord e um servidor onde você tenha permissão de Gerenciar Servidor
• Um aplicativo Discord criado no Portal do Desenvolvedor do Discord
• O token do bot do Portal do Desenvolvedor
• O bot convidado para o seu servidor com o escopo applications.commands

Passos para criar e executar um bot de comandos de barra

Siga estes passos para construir um bot que responda a /hello com uma saudação.

1. Instale o discord.py 2.0
   Abra um terminal e execute pip install -U discord.py. Verifique a versão com pip show discord.py. A versão deve ser 2.0.0 ou superior.
2. Crie um arquivo Python para o bot
   Crie um arquivo chamado bot.py e abra-o em um editor de código. Escreva as declarações de importação no topo: import discord e from discord.ext import commands.
3. Defina a instância do bot com intents
   Escreva o seguinte código para criar uma instância do bot. Intents são necessários para que o bot receba eventos. Para comandos de barra, você precisa pelo menos dos intents padrão.
   intents = discord.Intents.default()
bot = commands.Bot(command_prefix='/', intents=intents)
4. Adicione um evento para quando o bot estiver pronto
   Escreva um evento on_ready que imprima uma mensagem quando o bot conectar. Isso confirma que o bot está online.
   @bot.event
async def on_ready():
print(f'Logado como {bot.user}')
5. Crie um comando de barra usando a árvore
   Use o decorador @bot.tree.command para definir um comando de barra chamado hello. O nome da função se torna o nome do comando, a menos que você especifique um parâmetro name.
   @bot.tree.command(name="hello", description="Diz olá")
async def hello(interaction: discord.Interaction):
await interaction.response.send_message(f"Olá, {interaction.user.mention}!")
6. Sincronize a árvore de comandos
   Após definir os comandos, chame bot.tree.sync() dentro do evento on_ready ou em uma função de configuração separada. Isso envia as definições dos comandos para os servidores do Discord. O bot deve estar em um servidor para que os comandos apareçam.
   @bot.event
async def on_ready():
await bot.tree.sync()
print(f'Logado como {bot.user}')
7. Execute o bot com seu token
   No final do arquivo, adicione bot.run('SEU_TOKEN_DO_BOT'). Substitua SEU_TOKEN_DO_BOT pelo token real do Portal do Desenvolvedor. Não compartilhe este token.
8. Inicie o bot
   Execute python bot.py no terminal. Você deve ver a mensagem de logado. Abra o Discord e digite /hello em qualquer canal onde o bot tenha acesso. O bot deve responder com uma saudação.

Problemas comuns ao construir bots de comandos de barra

Comandos não aparecem no Discord

A causa mais comum é que a árvore de comandos não foi sincronizada. Certifique-se de chamar await bot.tree.sync() depois que todos os comandos forem definidos. Se você adicionar ou remover comandos depois, deve sincronizar novamente. Verifique também se o bot tem o escopo applications.commands quando você o convida. Use o gerador de URL OAuth2 no Portal do Desenvolvedor e selecione os escopos bot e applications.commands.

Bot não responde a comandos de barra

Verifique se o seu bot está online na lista de membros do servidor do Discord. Se o bot estiver online mas não responder, a interação pode estar expirando. O Discord espera uma resposta em até três segundos. Se o seu código demorar mais, use await interaction.response.defer() primeiro e depois envie um follow-up com await interaction.followup.send(). Verifique também se o bot tem as permissões necessárias no canal.

Opções do comando de barra não funcionam

Ao adicionar opções a um comando de barra, use o decorador @app_commands.describe() ou passe os parâmetros diretamente. Por exemplo:
@bot.tree.command(name="saudar", description="Sauda um usuário")
@app_commands.describe(usuario="O usuário a ser saudado")
async def saudar(interaction: discord.Interaction, usuario: discord.Member):
await interaction.response.send_message(f"Olá, {usuario.mention}!")
As opções devem ter dicas de tipo como str, int, discord.Member ou discord.Role. Se o tipo estiver errado, o comando não será registrado.

Comandos funcionam localmente, mas não após hospedagem

Se você mover seu bot para um servidor em nuvem, certifique-se de que o ambiente Python tenha o discord.py 2.0 instalado. Verifique também se o token do bot está definido como uma variável de ambiente em vez de codificado. Use os.getenv('DISCORD_TOKEN') para ler o token do ambiente. Isso evita exposição acidental.

Comparação: Comandos de barra do discord.py 2.0 vs Comandos tradicionais com prefixo

Funcionalidade	Comandos de Barra (discord.py 2.0)	Comandos Tradicionais com Prefixo
Interface do usuário	Aparece na lista de comandos com preenchimento automático e descrições	Sem interface, usuários precisam lembrar o prefixo e o nome do comando
Controle de permissão	Pode exigir permissões específicas por comando, aplicadas pelo Discord	Deve verificar permissões manualmente no código
Validação de entrada	Opções são tipadas e validadas pelo Discord antes de enviar ao bot	O bot deve analisar e validar argumentos do texto da mensagem
Latência	A interação deve ser reconhecida em até 3 segundos, depois é permitido follow-up	O bot pode levar o tempo que precisar para processar e responder
Disponibilidade global	Comandos sincronizam globalmente, mas podem levar até uma hora para aparecer em todos os servidores	Comandos ficam disponíveis imediatamente após o bot iniciar

Agora você tem um bot do Discord funcional que usa comandos de barra. O próximo passo é adicionar mais comandos com opções e preenchimento automático. Você também pode criar grupos de comandos usando @bot.tree.command(guild=discord.Object(id=GUILD_ID)) para testar comandos em um único servidor antes de torná-los globais. Use a documentação do discord.app_commands para explorar recursos avançados como menus de contexto e cooldowns.