Os modais de bot do Discord são janelas pop-up que permitem que os usuários preencham formulários diretamente no Discord. Eles substituem o método antigo de coletar entradas por meio de várias mensagens do bot ou argumentos de comando longos. Os modais suportam entradas de texto, parágrafos curtos e longos, e validação antes do envio. Este artigo explica o que são modais, como funcionam e como configurá-los no código do seu bot.
Os modais foram introduzidos pelo Discord em 2022 como parte da Interactions API. Eles permitem que bots coletem dados estruturados dos usuários sem poluir um canal. Você pode usar modais para formulários de inscrição, relatórios de bugs, enquetes ou qualquer entrada com vários campos. O formulário aparece sobre o cliente do Discord e o usuário o envia com um único clique.
Este guia cobre a estrutura do modal, permissões necessárias, exemplos de código usando discord.py e erros comuns a evitar. Após a leitura, você será capaz de implementar um modal que coleta feedback do usuário ou dados de registro.
Principais Conclusões: Modais de Bot do Discord para Entrada de Formulário
- Envio do modal via InteractionResponse.send_modal(): Envia um formulário modal para o usuário que aparece como uma janela pop-up.
- TextInput com estilo short ou paragraph: Coleta texto de linha única ou várias linhas dos usuários dentro do modal.
- Callback on_modal_submit: Manipula os dados após o usuário clicar em Enviar, permitindo processar a entrada.
O Que São Modais de Bot do Discord e Por Que Você Precisa Deles
Modais são componentes interativos que permitem que bots exibam um formulário com um ou mais campos de texto. Diferente dos comandos de barra, que aceitam argumentos limitados, os modais podem coletar vários campos em uma única interação. Eles são acionados por uma ação do usuário, como um comando de barra, clique em botão ou escolha em menu de seleção.
Cada modal tem um ID personalizado, um título exibido no topo e um ou mais componentes TextInput. Cada TextInput tem um rótulo, texto de placeholder, estilo (short ou paragraph), comprimento mínimo e máximo, e se é obrigatório. O usuário preenche os campos e clica em Enviar. O bot recebe uma interação de envio de modal contendo todos os valores.
Modais são úteis para qualquer cenário onde você precisa de mais de uma informação. Por exemplo, um modal de relatório de bug pode coletar o título do problema, descrição, passos para reproduzir e nível de gravidade. Um modal de registro pode coletar nome de usuário, email e preferência de cargo. Como o formulário aparece em um pop-up, o usuário permanece no mesmo canal e não vê várias mensagens do bot.
Para usar modais, seu bot deve ter o escopo applications.commands habilitado. Isso já é necessário para comandos de barra. Nenhuma permissão adicional do bot é necessária para os modais em si, mas o bot deve ser capaz de enviar mensagens no canal onde o modal é acionado.
Passos para Criar e Manipular um Modal de Bot do Discord
Os passos a seguir assumem que você tem um bot configurado com discord.py versão 2.0 ou posterior. Versões mais antigas não suportam modais. Você também precisa habilitar a intenção message_content se seu bot usar comandos de prefixo para acionar o modal, mas acionamentos de modal via comandos de barra não exigem essa intenção.
- Importe as classes de modal de discord.ui
No código do seu bot, importe Modal e TextInput de discord.ui. Também importe Interaction e AppCommand se você estiver usando comandos de barra. Exemplo:from discord.ui import Modal, TextInput. - Defina uma classe de modal que herda de discord.ui.Modal
Crie uma nova classe, por exemplo FeedbackModal. Dentro da classe, defina variáveis TextInput como atributos de classe. Cada TextInput requer um label, placeholder, style (discord.TextStyle.short ou discord.TextStyle.paragraph), min_length, max_length e required (True ou False). Você também pode definir um valor default. Exemplo:name = TextInput(label="Seu nome", placeholder="João Silva", style=discord.TextStyle.short, required=True). - Sobrescreva o método on_submit
Dentro da sua classe de modal, defina async def on_submit(self, interaction: Interaction):. Este método é executado quando o usuário clica em Enviar. Acesse os valores usando self.children[indice].value ou referenciando o nome do atributo diretamente, como self.name.value. Processe os dados conforme necessário e então envie uma resposta com interaction.response.send_message(). - Adicione um comando de barra que envia o modal
Crie um comando de barra usando @bot.tree.command(). Dentro do comando, chame await interaction.response.send_modal(FeedbackModal()). O modal aparecerá para o usuário imediatamente. Exemplo:@bot.tree.command(name="feedback", description="Envie feedback usando um modal")depoisasync def feedback(interaction: Interaction): await interaction.response.send_modal(FeedbackModal()). - Sincronize a árvore de comandos
No código de inicialização do seu bot, chame await bot.tree.sync() para registrar o comando de barra no Discord. Você só precisa sincronizar uma vez por inicialização do bot, a menos que altere comandos com frequência durante o desenvolvimento. Após a sincronização, o comando aparece nos servidores do Discord onde seu bot tem o escopo applications.commands.
Erros Comuns e Limitações ao Usar Modais
O modal não aparece quando o usuário executa o comando
A causa mais comum é que o código do bot lança uma exceção antes de chamar send_modal(). Verifique seu console em busca de erros. Outra causa é que a classe do modal está definida incorretamente — certifique-se de que ela herda de discord.ui.Modal e que todos os atributos TextInput são definidos no nível da classe, não dentro de __init__. Verifique também se o bot tem o escopo applications.commands no servidor.
O envio do modal falha silenciosamente
Se o método on_submit lançar uma exceção, o usuário vê um pop-up de erro genérico. Coloque o código em on_submit dentro de um bloco try-except e use interaction.response.send_message() para informar o usuário sobre o erro. Certifique-se também de que on_submit sempre envia uma resposta — seja com send_message, edit_original_response ou defer. Se você não responder dentro de 3 segundos, a interação expira e o usuário vê uma falha.
Os valores do TextInput estão vazios mesmo que o usuário os tenha preenchido
Isso acontece quando você acessa self.children[indice].value mas o índice está errado. Acesse os valores pelo nome do atributo: self.name.value. Certifique-se também de que os atributos TextInput são definidos antes de __init__ ser chamado. Se você defini-los dentro de __init__, eles não serão reconhecidos como componentes do modal.
O modal tem muitos campos ou rótulos longos
O Discord limita os modais a 5 componentes TextInput. Cada rótulo pode ter até 45 caracteres. O texto do placeholder pode ter até 100 caracteres. O título pode ter até 45 caracteres. Se você exceder esses limites, o modal não será enviado e um erro será registrado. Planeje seus campos de formulário com cuidado.
O usuário não pode interagir com o modal depois que ele é descartado
Modais são efêmeros — uma vez que o usuário os fecha ou envia, ele não pode reabrir a mesma instância do modal. Se o usuário precisar editar sua entrada, seu bot deve fornecer um novo comando ou botão para acionar o modal novamente. Você não pode editar um modal depois que ele é enviado.
| Item | Argumentos de Comando de Barra | Formulário Modal |
|---|---|---|
| Número de campos | Até 25 argumentos opcionais | Até 5 componentes TextInput |
| Tipos de campo | String, inteiro, booleano, usuário, canal, cargo, mencionável | Apenas texto curto ou texto de parágrafo |
| Experiência do usuário | Digitado na barra de chat, limitado pela interface do Discord | Janela pop-up com rótulos e placeholders |
| Validação | Validação básica de tipo pelo Discord | Validação personalizada no método on_submit |
| Melhor para | Comandos rápidos de entrada única | Formulários com vários campos e dados estruturados |
Modais são uma forma poderosa de coletar entrada de formulário de usuários do Discord. Eles mantêm a interface limpa e permitem a coleta de dados complexos sem poluir o chat. Agora você pode criar um modal para feedback, registro ou qualquer entrada com vários campos. Para estender seu bot, tente adicionar um botão que abre o modal em vez de um comando de barra. Um próximo passo prático é armazenar os dados enviados em um banco de dados ou enviá-los para um webhook para processamento.