Como Usar Webhook do Discord com Mecanismos de Template Personalizados como Handlebars

Webhooks do Discord permitem enviar mensagens automáticas para um canal de texto sem usar um bot. Você monta um payload JSON com campos de conteúdo, embeds e nome de usuário. Mas quando precisa enviar mensagens personalizadas para muitos usuários ou eventos, construir cada payload JSON manualmente se torna tedioso. Mecanismos de template como Handlebars permitem definir um modelo de mensagem uma vez e preenchê-lo com dados dinâmicos. Este artigo explica como combinar webhooks do Discord com Handlebars para gerar mensagens personalizadas a partir de qualquer fonte de dados.

O que é um Webhook do Discord e Por Que Usar um Mecanismo de Template

Um webhook do Discord é um endpoint HTTPS simples que aceita uma requisição POST com um corpo JSON. O JSON pode incluir campos como content para texto simples, embeds para objetos de embed ricos, username para sobrescrever o nome do webhook e avatar_url para um ícone personalizado. Você pode enviar a requisição de qualquer linguagem de programação ou ferramenta de automação.

O problema é que codificar manualmente cada mensagem rapidamente se torna propenso a erros quando você tem muitos usuários ou eventos. Por exemplo, enviar uma mensagem de boas-vindas para 500 novos membros requer 500 payloads diferentes. Um mecanismo de template como Handlebars resolve isso permitindo que você escreva a estrutura da mensagem uma vez e insira variáveis como {{username}} ou {{join_date}}.

Handlebars é uma linguagem de template sem lógica. Suporta condicionais ({{#if}}), loops ({{#each}}) e parciais para blocos reutilizáveis. Quando combinado com webhooks do Discord, você pode gerar layouts de embed complexos que mudam dependendo dos dados fornecidos.

Pré-requisitos para Usar Handlebars com Webhooks do Discord

Antes de começar, você precisa dos seguintes itens prontos:

• Uma URL de webhook do Discord. No Discord, vá em Configurações do Servidor > Integrações > Webhooks. Clique em Novo Webhook, nomeie, selecione um canal e copie a URL.
• Node.js instalado no seu sistema (versão 16 ou superior). Você usará npm para instalar os pacotes axios e handlebars.
• Uma fonte de dados. Pode ser um arquivo JSON, uma consulta de banco de dados ou uma resposta de API. Para este artigo, usamos um array JSON estático de objetos de usuário.

Passos para Criar um Template Handlebars e Enviar um Webhook do Discord

1. Configurar o Projeto Node.js

1. Crie uma pasta para o projeto
   Abra um terminal e execute mkdir discord-webhook-handlebars && cd discord-webhook-handlebars.
2. Inicialize o npm
   Execute npm init -y para criar um arquivo package.json com valores padrão.
3. Instale as dependências
   Execute npm install axios handlebars. Isso instala o cliente HTTP e o mecanismo de template.

2. Criar um Arquivo de Template Handlebars

Crie um arquivo chamado welcome-template.hbs com o seguinte conteúdo:

{
  "content": "Bem-vindo ao servidor, {{username}}!",
  "embeds": [
    {
      "title": "Novo Membro",
      "description": "{{username}} entrou em {{join_date}}.",
      "color": "{{color}}",
      "fields": [
        {
          "name": "Cargos",
          "value": "{{roles}}"
        }
      ]
    }
  ],
  "username": "Bot de Boas-Vindas"
}

As chaves duplas {{variavel}} são placeholders do Handlebars. Quando você compila este template com um objeto de dados, o Handlebars substitui cada placeholder pelo valor correspondente do objeto de dados.

3. Escrever o Script Node.js

Crie um arquivo chamado send-webhook.js e adicione o seguinte código:

const axios = require('axios');
const Handlebars = require('handlebars');
const fs = require('fs');

// Lê o arquivo de template
const templateSource = fs.readFileSync('welcome-template.hbs', 'utf8');
const template = Handlebars.compile(templateSource);

// Dados de exemplo
const users = [
  { username: 'Alice', join_date: '2024-03-15', color: 3447003, roles: 'Membro' },
  { username: 'Bob', join_date: '2024-03-16', color: 15277667, roles: 'Membro, Booster' }
];

// URL do webhook do Discord (substitua pela sua)
const webhookUrl = 'https://discord.com/api/webhooks/seu-webhook-id/seu-webhook-token';

async function sendWebhook(payload) {
  try {
    const response = await axios.post(webhookUrl, payload, {
      headers: { 'Content-Type': 'application/json' }
    });
    console.log('Mensagem enviada:', response.status);
  } catch (error) {
    console.error('Erro ao enviar webhook:', error.response?.data || error.message);
  }
}

// Percorre cada usuário e envia uma mensagem personalizada
users.forEach(user => {
  const renderedPayload = JSON.parse(template(user));
  sendWebhook(renderedPayload);
});

O script lê o template, compila com Handlebars e então itera sobre o array de usuários. Para cada usuário, renderiza o template com os dados desse usuário, converte a string resultante em um objeto JSON e envia para o webhook do Discord.

4. Executar o Script

No terminal, execute node send-webhook.js. Você deve ver duas mensagens aparecerem no seu canal do Discord — uma para Alice e outra para Bob.

Erros Comuns e Coisas a Evitar

Duplo Escape de Strings JSON

Quando você usa {{variavel}} dentro de um template JSON, o Handlebars escapa caracteres HTML por padrão. Se sua variável contém Markdown válido ou conteúdo de embed, o escape quebra a formatação. Para evitar isso, use chaves triplas {{{variavel}}} ou registre um helper do Handlebars que produza texto bruto.

JSON Inválido Após Renderização

Se uma variável contém uma quebra de linha ou aspas duplas, o JSON renderizado pode se tornar inválido. Sempre sanitize a entrada do usuário antes de passá-la para o template. Use uma função helper para escapar aspas duplas e remover quebras de linha dentro de valores de string.

Variáveis Ausentes Causam Strings Vazias

Se um objeto de dados não contém uma variável referenciada, o Handlebars produz uma string vazia. Isso pode gerar conteúdo de embed inesperado. Use o helper {{#if}} para incluir campos condicionalmente apenas quando a variável existir.

Webhook do Discord vs Bot: Principais Diferenças

Item	Webhook	Bot
Configuração	Criado nas Configurações do Servidor, sem necessidade de código	Registrar aplicação no Portal do Desenvolvedor do Discord
Permissões	Fixadas nas permissões do criador do webhook	Granulares via escopos OAuth2 e tokens de bot
Limites de Taxa	30 requisições por segundo por webhook	50 requisições por segundo por bot
Tipos de Mensagem	Texto simples, embeds, arquivos	Mesmo mais comandos de barra, botões, modais
Identidade do Usuário	Exibe como nome do webhook, não como um usuário	Exibe como o usuário do bot
Integração com Mecanismo de Template	Simples com Handlebars em qualquer linguagem	Possível, mas requer suporte de biblioteca para componentes

Webhooks são ideais para mensagens automáticas simples onde você não precisa de recursos interativos. Bots são melhores quando você precisa de comandos de barra, botões ou assinaturas de eventos em tempo real.

Agora você pode gerar mensagens personalizadas do Discord usando templates Handlebars. Comece criando um template para sua notificação mais comum — por exemplo, boas-vindas a novos membros ou uma atualização do servidor. Para estender o script, adicione helpers Handlebars para formatar datas ou truncar textos longos. Para uso avançado, integre o template com uma consulta de banco de dados para que cada webhook envie mensagens para os registros mais recentes.