Criar um bot para Discord usando Python é uma excelente forma de automatizar tarefas, gerenciar servidores e adicionar funcionalidades personalizadas à sua comunidade. Neste guia completo, você vai aprender desde a configuração inicial até a implementação de comandos avançados, tudo de forma prática e acessível.
O Discord se tornou uma das plataformas mais populares para comunidades online, e os bots são ferramentas essenciais para melhorar a experiência dos usuários. Com Python, você pode criar soluções automatizadas que vão desde boas-vindas a novos membros até sistemas complexos de moderação.
Se você está começando sua jornada no desenvolvimento de bots, confira este excelente tutorial do canal Pedro Ricardo – PR que ensina de forma didática como criar bots para Discord:
Vídeo tutorial do canal Pedro Ricardo – PR sobre criação de bots Discord com Python
O Que é um Bot do Discord
Um bot do Discord é um programa automatizado que se conecta à plataforma e executa tarefas específicas. Esses bots funcionam como usuários especiais que podem responder a comandos, reagir a eventos e interagir com membros do servidor.
Os bots podem realizar diversas funções. Alguns enviam mensagens de boas-vindas para novos membros. Outros tocam música nos canais de voz. Existem também bots que moderam conversas, removendo conteúdo inadequado automaticamente.
A biblioteca discord.py é a ferramenta mais popular para criar bots Discord com Python. Ela oferece acesso completo à API do Discord e permite que você desenvolva bots poderosos sem precisar lidar diretamente com requisições HTTP complexas.
Python é ideal para esse tipo de projeto porque tem uma sintaxe simples e clara. Se você já conhece os fundamentos de Python, criar um bot básico leva menos de uma hora. Mesmo quem está aprendendo Python do zero consegue seguir os passos sem dificuldades.
Pré-Requisitos para Criar Seu Bot
Antes de começar a programar seu bot, você precisa preparar o ambiente de desenvolvimento. Os requisitos são simples e todo o processo é gratuito.
Python Instalado no Computador
Você vai precisar do Python versão 3.8 ou superior instalado no seu sistema. Se você ainda não tem Python, veja nosso guia completo sobre como instalar Python no Windows, Mac ou Linux.
Para verificar se o Python está instalado, abra o terminal ou prompt de comando e digite:
python --versionSe aparecer algo como “Python 3.10.0” ou superior, você está pronto para continuar.
Conta no Discord
Você precisa de uma conta no Discord para acessar o portal de desenvolvedores. Se você ainda não tem uma, crie gratuitamente em discord.com. A conta será usada para criar a aplicação do bot e para testá-lo em um servidor.
Editor de Código
Um bom editor facilita muito o trabalho. Existem várias opções excelentes e gratuitas. O Visual Studio Code é uma das escolhas mais populares. Se você usa VS Code, confira as melhores extensões para Python.
Outras opções incluem o PyCharm, que é uma IDE completa para Python, ou até mesmo o IDLE do Python que já vem instalado com o Python.
Criando a Aplicação no Discord Developer Portal
O primeiro passo prático é criar uma aplicação no portal de desenvolvedores do Discord. Essa aplicação vai gerar o token que seu bot usará para se conectar.
Passo 1: Acesse o Discord Developer Portal em discord.com/developers/applications. Faça login com sua conta do Discord.
Passo 2: Clique no botão “New Application” no canto superior direito. Escolha um nome para sua aplicação. Esse nome pode ser diferente do nome que o bot terá mais tarde.
Passo 3: Na barra lateral esquerda, clique em “Bot”. Depois clique em “Add Bot” e confirme clicando em “Yes, do it!”.
Passo 4: Agora você verá as configurações do seu bot. Role a página até encontrar a seção “TOKEN”. Clique em “Reset Token” e depois em “Copy” para copiar o token.
Importante: Guarde esse token em um lugar seguro. Nunca compartilhe seu token publicamente ou adicione ele diretamente no código que você vai enviar para o GitHub. Qualquer pessoa com acesso ao token pode controlar seu bot.
Passo 5: Na seção “Privileged Gateway Intents”, ative as opções “PRESENCE INTENT”, “SERVER MEMBERS INTENT” e “MESSAGE CONTENT INTENT”. Essas permissões são necessárias para o bot receber informações sobre mensagens e membros do servidor.
Adicionando o Bot ao Seu Servidor
Agora que você criou o bot no portal de desenvolvedores, precisa adicioná-lo a um servidor Discord para poder testá-lo.
Passo 1: No Developer Portal, vá para a seção “OAuth2” no menu lateral e depois clique em “URL Generator”.
Passo 2: Em “SCOPES”, marque a opção “bot”.
Passo 3: Em “BOT PERMISSIONS”, você pode escolher as permissões que o bot terá. Para começar, você pode selecionar “Administrator” para dar todas as permissões. Mas em projetos reais, é melhor escolher apenas as permissões necessárias.
Passo 4: Copie a URL gerada na parte inferior da página e cole no seu navegador. Selecione o servidor onde você quer adicionar o bot e clique em “Autorizar”.
Pronto! O bot agora aparece na lista de membros do seu servidor, mas ele ainda está offline porque não escrevemos o código.
Instalando a Biblioteca discord.py
Para instalar bibliotecas no Python, usamos o gerenciador de pacotes pip. A biblioteca discord.py é a que vamos usar para conectar nosso código ao Discord.
Abra o terminal ou prompt de comando e execute o seguinte comando:
pip install discord.pySe você estiver no Linux ou Mac, pode precisar usar:
pip3 install discord.pyO pip vai baixar e instalar a biblioteca junto com todas as dependências necessárias. Esse processo leva alguns minutos.
Para projetos mais organizados, é recomendado criar um ambiente virtual antes de instalar as bibliotecas. Isso mantém as dependências do seu projeto isoladas de outros projetos Python.
Criando o Primeiro Bot Básico
Agora vamos escrever o código do nosso primeiro bot. Crie um arquivo chamado bot.py no seu editor de código favorito.
Veja o código básico para um bot funcional:
import discord
from discord.ext import commands
# Substitua pelo seu token
TOKEN = 'seu_token_aqui'
# Define o prefixo dos comandos
bot = commands.Bot(command_prefix='!', intents=discord.Intents.all())
@bot.event
async def on_ready():
print(f'{bot.user} está online!')
@bot.command()
async def ola(ctx):
await ctx.send(f'Olá, {ctx.author.name}!')
bot.run(TOKEN)Vamos entender cada parte desse código:
A primeira linha importa a biblioteca discord. Na segunda linha, importamos o módulo commands que facilita a criação de comandos.
A variável TOKEN guarda o token do seu bot. Substitua ‘seu_token_aqui’ pelo token que você copiou do Developer Portal.
Criamos uma instância do bot usando commands.Bot. O command_prefix define que todos os comandos começam com o caractere “!”. O parâmetro intents especifica quais eventos o bot pode receber.
O decorador @bot.event marca uma função como um evento. O evento on_ready é executado quando o bot se conecta com sucesso ao Discord.
O decorador @bot.command() transforma uma função em um comando que usuários podem executar. No exemplo, criamos o comando !ola que responde com uma saudação.
Para executar o bot, salve o arquivo e execute no terminal:
python bot.pySe tudo estiver correto, você verá a mensagem “NomeDoBot está online!” no terminal. Vá até seu servidor Discord e digite !ola em qualquer canal. O bot deve responder com uma saudação personalizada!
Protegendo o Token com Variáveis de Ambiente
Nunca deixe seu token diretamente no código. Se você compartilhar o código ou subir para o GitHub, outras pessoas terão acesso ao token e poderão controlar seu bot.
A forma correta é usar um arquivo .env para guardar informações sensíveis. Primeiro, instale a biblioteca python-dotenv:
pip install python-dotenvCrie um arquivo chamado .env na mesma pasta do seu bot:
DISCORD_TOKEN=seu_token_aquiAgora modifique seu código para carregar o token do arquivo .env:
import discord
from discord.ext import commands
import os
from dotenv import load_dotenv
load_dotenv()
TOKEN = os.getenv('DISCORD_TOKEN')
bot = commands.Bot(command_prefix='!', intents=discord.Intents.all())
@bot.event
async def on_ready():
print(f'{bot.user} está online!')
@bot.command()
async def ola(ctx):
await ctx.send(f'Olá, {ctx.author.name}!')
bot.run(TOKEN)Não se esqueça de adicionar o arquivo .env ao .gitignore se você for usar Git para versionar seu código.
Criando Comandos Personalizados
Os comandos são a forma mais comum de interagir com bots. Vamos criar alguns comandos diferentes para entender melhor como funcionam.
Comando com Argumentos
Um comando pode receber informações do usuário. Veja um exemplo de comando que repete o que o usuário escrever:
@bot.command()
async def repetir(ctx, *, mensagem):
await ctx.send(mensagem)O asterisco * antes de mensagem captura todos os argumentos após o comando como uma única string. Agora você pode usar: !repetir Olá mundo!
Comando com Cálculos
Vamos criar um comando que soma dois números:
@bot.command()
async def somar(ctx, num1: int, num2: int):
resultado = num1 + num2
await ctx.send(f'A soma de {num1} + {num2} é {resultado}')Os dois pontos depois dos parâmetros indicam o tipo esperado. Se o usuário digitar algo que não é número, o discord.py vai gerar um erro automaticamente.
Comando com Informações do Servidor
Um comando útil mostra informações sobre o servidor:
@bot.command()
async def info(ctx):
servidor = ctx.guild
mensagem = f'''
**Nome do Servidor:** {servidor.name}
**Membros:** {servidor.member_count}
**Criado em:** {servidor.created_at.strftime("%d/%m/%Y")}
'''
await ctx.send(mensagem)O objeto ctx.guild contém informações sobre o servidor onde o comando foi executado.
Trabalhando com Eventos
Além de comandos, os bots podem reagir a eventos que acontecem no servidor. Eventos são ações como um novo membro entrando, alguém enviando uma mensagem ou o bot sendo adicionado a um servidor.
Mensagem de Boas-Vindas
Um dos eventos mais usados é dar boas-vindas a novos membros:
@bot.event
async def on_member_join(member):
canal = member.guild.system_channel
if canal:
mensagem = f'Bem-vindo(a) ao servidor, {member.mention}! 🎉'
await canal.send(mensagem)Esse código envia uma mensagem de boas-vindas no canal padrão do servidor sempre que um novo membro entrar.
Detecção de Palavras
O bot pode reagir a mensagens específicas sem precisar de um comando:
@bot.event
async def on_message(message):
# Ignora mensagens do próprio bot
if message.author == bot.user:
return
# Responde quando alguém menciona Python
if 'python' in message.content.lower():
await message.channel.send('Você falou de Python! 🐍')
# Importante: processa os comandos normalmente
await bot.process_commands(message)A linha await bot.process_commands(message) é essencial. Sem ela, os comandos normais param de funcionar quando você usa o evento on_message.
Formatando Mensagens com Embeds
As mensagens embed são aquelas caixas coloridas e organizadas que muitos bots usam. Elas deixam as respostas do bot muito mais profissionais e fáceis de ler.
Veja como criar um embed básico:
@bot.command()
async def sobre(ctx):
embed = discord.Embed(
title='Sobre Este Bot',
description='Um bot criado para ajudar a comunidade!',
color=discord.Color.blue()
)
embed.add_field(name='Linguagem', value='Python', inline=True)
embed.add_field(name='Biblioteca', value='discord.py', inline=True)
embed.set_footer(text='Criado em 2025')
embed.set_thumbnail(url=bot.user.avatar.url)
await ctx.send(embed=embed)Os embeds aceitam vários tipos de conteúdo. Você pode adicionar campos, imagens, rodapé e escolher cores personalizadas. O parâmetro inline=True coloca os campos lado a lado.
Tratamento de Erros
Quando um usuário usa um comando incorretamente, é importante mostrar uma mensagem de erro clara. O discord.py permite capturar erros específicos.
Veja um exemplo de tratamento de erros com o comando de soma que criamos antes:
@somar.error
async def somar_error(ctx, error):
if isinstance(error, commands.MissingRequiredArgument):
await ctx.send('Você precisa fornecer dois números! Exemplo: !somar 5 3')
elif isinstance(error, commands.BadArgument):
await ctx.send('Por favor, use apenas números! Exemplo: !somar 5 3')Esse código captura dois tipos de erros comuns. O MissingRequiredArgument acontece quando o usuário não fornece todos os argumentos. O BadArgument ocorre quando os argumentos são do tipo errado.
Para entender melhor como funcionam os erros em Python, veja nosso guia sobre try except em Python.
Trabalhando com Dados Persistentes
Muitas vezes você quer que o bot lembre de informações mesmo depois de ser desligado. Para isso, você precisa salvar dados em arquivos ou bancos de dados.
Usando JSON para Salvar Dados
Uma forma simples de guardar dados é usando arquivos JSON:
import json
@bot.command()
async def guardar(ctx, *, texto):
dados = {}
# Tenta carregar dados existentes
try:
with open('dados.json', 'r') as arquivo:
dados = json.load(arquivo)
except FileNotFoundError:
pass
# Adiciona novo dado
dados[str(ctx.author.id)] = texto
# Salva de volta no arquivo
with open('dados.json', 'w') as arquivo:
json.dump(dados, arquivo)
await ctx.send('Dados guardados com sucesso!')
@bot.command()
async def recuperar(ctx):
try:
with open('dados.json', 'r') as arquivo:
dados = json.load(arquivo)
texto = dados.get(str(ctx.author.id))
if texto:
await ctx.send(f'Seus dados: {texto}')
else:
await ctx.send('Você não tem dados guardados.')
except FileNotFoundError:
await ctx.send('Nenhum dado foi guardado ainda.')Esse sistema simples permite que cada usuário guarde e recupere informações. Para projetos maiores, considere usar um banco de dados como SQLite ou PostgreSQL.
Adicionando Reações e Interações
Os bots podem adicionar reações (emojis) às mensagens e responder quando usuários clicam nelas. Isso cria experiências interativas interessantes.
@bot.command()
async def votacao(ctx, *, pergunta):
mensagem = await ctx.send(f'📊 **Votação:** {pergunta}')
await mensagem.add_reaction('👍')
await mensagem.add_reaction('👎')
# Espera por uma reação
def check(reaction, user):
return user == ctx.author and str(reaction.emoji) in ['👍', '👎']
try:
reaction, user = await bot.wait_for('reaction_add', timeout=30.0, check=check)
await ctx.send(f'{user.name} votou {reaction.emoji}')
except:
await ctx.send('Tempo esgotado!')O método wait_for pausa a execução até que um evento específico aconteça. O parâmetro timeout define quanto tempo esperar antes de desistir.
Organizando o Código com Cogs
Quando seu bot cresce e tem muitos comandos, é importante organizar o código. Os Cogs são extensões que agrupam comandos relacionados em arquivos separados.
Crie um arquivo chamado comandos_gerais.py:
from discord.ext import commands
class ComandosGerais(commands.Cog):
def __init__(self, bot):
self.bot = bot
@commands.command()
async def ping(self, ctx):
await ctx.send('Pong!')
@commands.command()
async def teste(self, ctx):
await ctx.send('Comando de teste funcionando!')
async def setup(bot):
await bot.add_cog(ComandosGerais(bot))No arquivo principal do bot, carregue o Cog:
import discord
from discord.ext import commands
import asyncio
bot = commands.Bot(command_prefix='!', intents=discord.Intents.all())
async def load_extensions():
await bot.load_extension('comandos_gerais')
async def main():
async with bot:
await load_extensions()
await bot.start(TOKEN)
asyncio.run(main())Essa estrutura mantém o código organizado e facilita muito a manutenção de bots maiores. Você pode criar vários Cogs para diferentes categorias de comandos.
Hospedando Seu Bot na Nuvem
Para que seu bot fique online o tempo todo, você precisa hospedá-lo em um servidor. Existem várias opções gratuitas e pagas.
Replit é uma plataforma gratuita que permite executar código Python direto no navegador. É ótima para começar, mas tem limitações de tempo de execução.
Heroku oferece um plano gratuito limitado que funciona bem para bots simples. Você precisará aprender sobre Git e deploy de aplicações.
DigitalOcean e AWS são opções pagas mais robustas. Elas dão controle total sobre o servidor, mas exigem conhecimento de administração de sistemas Linux.
Para projetos profissionais, vale a pena investir em uma VPS (Virtual Private Server) que garanta disponibilidade contínua.
Boas Práticas e Segurança
Seguir boas práticas garante que seu bot seja seguro e confiável.
Nunca exponha seu token. Use variáveis de ambiente e adicione o arquivo .env ao .gitignore.
Valide entradas do usuário. Sempre verifique se os dados fornecidos pelos usuários são válidos antes de processá-los.
Trate erros adequadamente. Não deixe que erros não tratados façam o bot parar de funcionar.
Use logging. Registre eventos importantes para facilitar a depuração de problemas.
Respeite os limites de taxa. A API do Discord tem limites de requisições por segundo. Não envie muitas mensagens rapidamente.
Siga as diretrizes do Discord. Leia e respeite os Termos de Serviço e as Diretrizes para Desenvolvedores do Discord.
Conhecer o PEP8 ajuda a escrever código Python mais limpo e profissional.
Recursos Avançados
Depois de dominar o básico, você pode adicionar funcionalidades mais complexas ao seu bot.
Integração com APIs externas permite buscar informações da internet. Você pode criar comandos que mostram previsão do tempo, cotação de moedas ou notícias usando a biblioteca requests.
Sistema de níveis e XP gamifica o servidor. Os membros ganham pontos por participar e sobem de nível.
Moderação automática detecta e remove spam, palavras ofensivas ou conteúdo inadequado.
Sistema de economia cria uma moeda virtual que membros podem ganhar e gastar em recompensas.
Música permite que o bot entre em canais de voz e toque músicas do YouTube.
Para projetos que exigem análise de dados ou manipulação de grandes quantidades de informações, conhecer Pandas pode ser muito útil.
Debugging e Resolução de Problemas
Quando algo não funciona como esperado, saber como investigar é fundamental.
Use print() para debug. Adicione mensagens de depuração para entender o fluxo do código.
Ative o logging. O discord.py tem um sistema de logging integrado:
import logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger('discord')Leia as mensagens de erro. As mensagens mostram exatamente onde e por que o código falhou.
Verifique as permissões. Muitos problemas acontecem porque o bot não tem permissão para executar certas ações.
Consulte a documentação. A documentação oficial do discord.py é muito completa e tem exemplos práticos.
Conhecer os erros mais comuns em Python ajuda a identificar e corrigir problemas rapidamente.
Perguntas Frequentes (FAQ)
1. Preciso saber Python avançado para criar um bot Discord?
Não. Conhecimentos básicos de Python são suficientes para criar bots simples. Você vai aprendendo conceitos avançados conforme desenvolve funcionalidades mais complexas.
2. Quanto custa criar e manter um bot Discord?
Criar um bot é totalmente gratuito. Os custos aparecem apenas se você quiser hospedar o bot em um servidor pago para mantê-lo online 24 horas.
3. Posso usar o mesmo bot em vários servidores Discord?
Sim. Um único bot pode funcionar em quantos servidores você quiser simultaneamente.
4. O que fazer se o bot não responde aos comandos?
Verifique se o bot está online no servidor, se os intents estão ativados corretamente e se você está usando o prefixo correto nos comandos.
5. Como faço para o bot tocar música no Discord?
Você precisa instalar bibliotecas adicionais como FFmpeg e youtube-dl. A funcionalidade de música é mais complexa e exige conhecimentos intermediários.
6. É seguro compartilhar o código do meu bot?
Sim, desde que você não inclua o token. Sempre use variáveis de ambiente e adicione o arquivo .env ao .gitignore antes de compartilhar o código.
7. Posso monetizar meu bot Discord?
Sim. Você pode cobrar por funcionalidades premium, aceitar doações ou oferecer o bot como serviço pago. Apenas respeite os termos de serviço do Discord.
8. Quanto tempo leva para criar um bot funcional?
Um bot básico com alguns comandos simples pode ser criado em 1-2 horas. Bots complexos com muitas funcionalidades podem levar semanas ou meses.
9. O discord.py funciona com a versão mais recente do Python?
Sim. O discord.py é compatível com Python 3.8 e versões superiores. Sempre use uma versão recente do Python para ter acesso aos recursos mais novos.
10. Como adicionar permissões específicas ao meu bot?
Configure as permissões no Developer Portal ao gerar a URL de convite. Você também pode ajustar permissões diretamente nas configurações do servidor Discord.
