Como Enviar um Webhook do Discord com um Comando de Aplicação Acionado pelo Bot

Os bots do Discord podem enviar mensagens para um canal usando um webhook em vez de uma mensagem normal do bot. Uma mensagem de webhook parece vir de um nome de usuário e avatar personalizados, não do próprio bot. Isso é útil quando você quer que a resposta de um comando pareça ter sido enviada por um usuário ou serviço específico. Muitos desenvolvedores de bots desejam acionar um webhook quando um usuário executa um comando de barra. Este artigo explica como configurar um bot que envia um webhook em resposta a um comando de aplicação.

O que é um Webhook do Discord e Por que Usá-lo com um Comando do Bot

Um webhook do Discord é uma forma de enviar mensagens para um canal programaticamente. Ao contrário de uma mensagem normal do bot que mostra o nome e avatar do bot, uma mensagem de webhook pode ter qualquer nome de usuário e avatar que você escolher. Isso torna os webhooks ideais para exibir notificações formatadas, estatísticas de jogos ou logs que parecem vir de um serviço externo.

Quando você envia um webhook a partir de um comando do bot, o fluxo funciona assim:

• Um usuário executa um comando de barra no seu servidor Discord.
• Seu bot recebe um evento InteractionCreate.
• O bot cria ou busca um webhook para o canal de destino.
• O bot envia a mensagem via webhook, usando um nome e avatar personalizados.
• O bot responde ao usuário com uma confirmação ou mensagem efêmera.

O principal benefício é a consistência visual. Por exemplo, um bot de gerenciamento de servidor pode enviar uma mensagem webhook que parece uma notificação do sistema em vez de uma resposta do bot. A mensagem webhook também não pode ser excluída por usuários sem a permissão Gerenciar Webhooks, o que adiciona uma camada de controle.

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

• Uma aplicação de bot do Discord criada no Portal do Desenvolvedor do Discord.
• O bot adicionado ao seu servidor com as permissões Enviar Mensagens e Gerenciar Webhooks.
• Node.js instalado na sua máquina de desenvolvimento.
• A biblioteca discord.js versão 14 ou posterior instalada no seu projeto.

Passos para Enviar um Webhook do Discord a partir de um Comando de Aplicação

A implementação usa discord.js e a classe WebhookClient. Siga estes passos para construir o recurso.

1. Configure seu Projeto e Instale as Dependências
   Crie uma nova pasta e inicialize um projeto Node.js. Execute npm init -y e depois instale o discord.js com npm install discord.js. Crie um arquivo chamado index.js.
2. Crie o Cliente do Bot e Registre um Comando de Barra
   No index.js, importe o discord.js e crie um cliente com a intent GatewayIntentBits.Guilds. Use o evento client.on('ready') para registrar um comando de barra global chamado webhook. O comando deve aceitar uma opção de string opcional para o conteúdo da mensagem.
3. Escute o Evento InteractionCreate
   Adicione um listener de evento para interactionCreate. Verifique se a interação é um comando de entrada de chat e se o nome do comando corresponde a webhook.
4. Busque ou Crie um Webhook para o Canal
   Dentro do manipulador do comando, obtenha o canal onde o comando foi executado usando interaction.channel. Use channel.fetchWebhooks() para ver se um webhook já existe. Se não, crie um com channel.createWebhook(). Armazene o ID e token do webhook para reutilização.
5. Crie um WebhookClient e Envie a Mensagem
   Use o ID e token do webhook para instanciar um WebhookClient. Chame webhookClient.send({ content: 'Sua mensagem aqui', username: 'Nome Personalizado', avatarURL: 'https://exemplo.com/avatar.png' }). Isso envia a mensagem webhook para o canal.
6. Responda ao Usuário
   Após a mensagem webhook ser enviada, responda à interação com interaction.reply({ content: 'Webhook enviado!', ephemeral: true }). Isso confirma a ação sem poluir o canal.

Aqui está um exemplo de código completo para o manipulador do comando:

const { Client, GatewayIntentBits, WebhookClient } = require('discord.js');
const client = new Client({ intents: [GatewayIntentBits.Guilds] });

client.once('ready', async () => {
  console.log(`Logado como ${client.user.tag}`);
  const command = {
    name: 'webhook',
    description: 'Enviar uma mensagem webhook',
    options: [
      {
        name: 'mensagem',
        description: 'O conteúdo da mensagem',
        type: 3, // STRING
        required: true,
      },
    ],
  };
  await client.application.commands.create(command);
});

client.on('interactionCreate', async (interaction) => {
  if (!interaction.isChatInputCommand()) return;
  if (interaction.commandName !== 'webhook') return;

  const channel = interaction.channel;
  let webhooks = await channel.fetchWebhooks();
  let webhook = webhooks.find(w => w.owner.id === client.user.id);

  if (!webhook) {
    webhook = await channel.createWebhook({
      name: 'Webhook do Bot',
    });
  }

  const webhookClient = new WebhookClient({ id: webhook.id, token: webhook.token });
  const messageContent = interaction.options.getString('mensagem');

  await webhookClient.send({
    content: messageContent,
    username: 'Nome Personalizado',
    avatarURL: 'https://exemplo.com/avatar.png',
  });

  await interaction.reply({ content: 'Webhook enviado!', ephemeral: true });
});

client.login('SEU_TOKEN_DO_BOT');

Substitua SEU_TOKEN_DO_BOT pelo token do seu bot no Portal do Desenvolvedor do Discord. O nome de usuário e URL do avatar do webhook estão codificados neste exemplo. Você pode torná-los dinâmicos adicionando opções de comando.

Problemas Comuns ao Enviar Webhooks a partir de Comandos do Bot

Webhook Não Criado Devido a Permissões Ausentes

Se o bot não tiver a permissão Gerenciar Webhooks, channel.createWebhook() lançará um erro. Certifique-se de que o cargo do bot tenha essa permissão ativada nas configurações do servidor. Verifique também se o bot tem a permissão Enviar Mensagens para o canal de destino.

Token do Webhook Expira Após Reinicialização do Bot

Um token de webhook é gerado quando o webhook é criado. Se você excluir o webhook e recriá-lo, o token muda. Armazene o ID e token do webhook em um banco de dados ou variável de ambiente para evitar perder o acesso. O token não expira a menos que o webhook seja excluído.

Mensagem Webhook Não Aparece no Canal

Se a mensagem webhook não aparecer, verifique se o ID do canal está correto. A propriedade interaction.channel retorna o canal onde o comando foi executado. Se você quiser enviar o webhook para um canal diferente, busque esse canal pelo ID usando client.channels.fetch().

Limites de Taxa ao Enviar Múltiplos Webhooks

O Discord aplica limites de taxa a mensagens webhook. O limite é de 30 mensagens por webhook a cada 60 segundos. Se o seu bot enviar muitos webhooks rapidamente, implemente uma fila ou atraso para evitar atingir o limite de taxa. Use uma biblioteca como p-limit para controlar a concorrência.

Item	WebhookClient.send()	channel.send()
Aparência da mensagem	Nome de usuário e avatar personalizados	Nome de usuário e avatar do bot
Permissão necessária	Gerenciar Webhooks e Enviar Mensagens	Apenas Enviar Mensagens
Pode ser excluída por usuários	Não, apenas por usuários com Gerenciar Webhooks	Sim, por qualquer usuário com Gerenciar Mensagens
Limite de taxa	30 a cada 60 segundos por webhook	5 a cada 5 segundos por canal
Suporta embeds	Sim	Sim

Agora você pode fazer seu bot enviar mensagens webhook quando um usuário executar um comando de barra. O webhook aparece com um nome e avatar personalizados, dando às respostas do comando uma aparência profissional. Para uso avançado, adicione opções de comando para permitir que os usuários definam o nome e avatar do webhook dinamicamente. Considere armazenar IDs de webhook em um banco de dados para que o bot possa reutilizá-los entre reinicializações.