Substituição de Nome de Usuário no Webhook do Discord: Como Personalizar

Ao enviar mensagens por um webhook do Discord, o nome do remetente padrão geralmente é o nome que você definiu ao criar o webhook. Talvez você queira exibir um nome diferente para cada mensagem automatizada, como um bot de clima mostrando “Bot do Clima” ou um servidor de jogo mostrando “Status do Servidor”. O Discord permite substituir o nome de usuário do webhook por mensagem usando a API do webhook. Este artigo explica como definir um nome personalizado ao enviar mensagens via webhook usando o campo username no payload JSON.

Como Funciona a Substituição do Nome de Usuário no Webhook do Discord

Um webhook do Discord é uma forma simples de enviar mensagens automatizadas para um canal de texto. Ao criar um webhook em um servidor, você define um nome e um avatar padrão. Cada mensagem enviada por esse webhook normalmente usa esse nome e avatar padrão. No entanto, a API do webhook permite alterar o nome de usuário e o avatar para cada mensagem individual, incluindo os campos username e avatar_url no payload JSON. Essa substituição não altera as configurações permanentes do webhook. Ela afeta apenas a mensagem específica enviada.

O recurso de substituição é útil quando um único webhook atende a vários propósitos. Por exemplo, um único webhook pode enviar alertas de diferentes serviços, cada um com seu próprio nome e ícone. Você também pode usá-lo para testar diferentes nomes de exibição sem criar vários webhooks. A substituição funciona com qualquer linguagem de programação ou ferramenta que possa enviar requisições HTTP POST com um corpo JSON.

Pré-requisitos para Usar a Substituição de Nome de Usuário

Antes de enviar uma mensagem de webhook com um nome de usuário personalizado, você precisa de:

• Um servidor Discord onde você tenha a permissão Gerenciar Webhooks. Geralmente, isso está disponível para moderadores e administradores do servidor.
• Uma URL de webhook de um canal de texto nesse servidor. Você pode criar ou copiar a URL do webhook em Configurações do Servidor > Integrações > Webhooks.
• Uma ferramenta ou script que possa enviar requisições HTTP POST para a URL do webhook. Ferramentas comuns incluem curl, Python, JavaScript (Node.js) e serviços sem código como IFTTT ou Zapier.

Passos para Enviar uma Mensagem de Webhook com Nome de Usuário Personalizado

Siga estes passos para enviar uma mensagem de webhook onde o nome do remetente é diferente do nome padrão do webhook.

1. Obtenha sua URL do webhook
   Abra o Discord e vá para o seu servidor. Clique no nome do servidor no canto superior esquerdo, depois selecione Configurações do Servidor > Integrações > Webhooks. Encontre o webhook que deseja usar e clique em Copiar URL do Webhook. Salve essa URL em um local seguro, pois qualquer pessoa com ela pode enviar mensagens para o seu canal.
2. Prepare seu payload JSON
   Crie um objeto JSON que inclua os campos que deseja enviar. A estrutura básica é:
   {
"username": "Seu Nome Personalizado",
"content": "Texto da sua mensagem aqui"
}
   O campo username é opcional. Se omitido, o Discord usa o nome padrão do webhook. O campo content contém o texto da mensagem. Você também pode adicionar avatar_url para definir um avatar personalizado para esta mensagem.
3. Envie a requisição POST
   Use sua ferramenta preferida para enviar uma requisição HTTP POST para a URL do webhook. A requisição deve ter o cabeçalho Content-Type definido como application/json. O corpo deve ser o payload JSON que você preparou. Aqui está um exemplo usando curl no terminal:
   curl -X POST -H "Content-Type: application/json" -d '{"username": "Bot do Clima", "content": "Temperatura atual: 22°C"}' SUA_URL_DO_WEBHOOK
   Substitua SUA_URL_DO_WEBHOOK pela URL real que você copiou.
4. Verifique o resultado no Discord
   Vá para o canal de texto onde o webhook está configurado. Você deve ver uma mensagem do nome de usuário personalizado que especificou. A mensagem também mostrará uma pequena tag “BOT” ao lado do nome, indicando que veio de um webhook.

Erros Comuns e Limitações ao Substituir Nomes de Usuário

Nome de Usuário Excede 80 Caracteres

O Discord limita o nome de usuário personalizado a 80 caracteres. Se você enviar um nome mais longo, o Discord ignora a substituição e usa o nome padrão do webhook. Sempre verifique o comprimento do seu nome personalizado antes de enviar.

Nome de Usuário Contém Caracteres Inválidos

O campo de nome de usuário aceita a maioria dos caracteres Unicode, mas o Discord pode remover ou ignorar certos caracteres, como espaços excessivos ou caracteres de controle especiais. Use letras, números, espaços e símbolos comuns.

URL do Avatar Falha ao Carregar

Se você também definir um avatar personalizado usando o campo avatar_url, a URL deve apontar para um arquivo de imagem publicamente acessível. O Discord suporta formatos JPG, PNG e GIF. Se a imagem falhar ao carregar, o Discord exibe o avatar padrão do webhook.

URL do Webhook Inválida ou Expirada

As URLs do webhook não expiram, mas podem ser excluídas por um administrador do servidor. Se você receber um erro 404 ao enviar a requisição, o webhook pode ter sido removido. Crie um novo webhook e atualize seu script com a nova URL.

Campos da Mensagem do Webhook do Discord: Payload JSON vs Configurações Padrão

Recurso	Configuração Padrão do Webhook	Substituição por Mensagem
Nome de Usuário	Definido ao criar o webhook	Definido no campo username
Avatar	Definido ao criar o webhook	Definido no campo avatar_url
Conteúdo da Mensagem	Obrigatório em todo POST	Definido no campo content
Embeds	Não disponível nos padrões	Definido no array embeds
Limite de Taxa	30 requisições por minuto	Mesmo limite se aplica

A substituição por mensagem altera apenas o nome de usuário e o avatar para aquela mensagem específica. O nome e avatar padrão do webhook permanecem inalterados para mensagens futuras que não incluam os campos de substituição.

Testando a Substituição de Nome de Usuário com um Script Simples

Se você quiser testar a substituição rapidamente, pode usar um script Python. A biblioteca requests do Python facilita o envio de requisições HTTP. Instale a biblioteca com pip install requests se não a tiver. Depois, use este script:

import requests

webhook_url = "SUA_URL_DO_WEBHOOK"
data = {
    "username": "Bot de Teste",
    "content": "Esta é uma mensagem de teste com nome de usuário personalizado."
}

response = requests.post(webhook_url, json=data)
print(response.status_code)

Substitua SUA_URL_DO_WEBHOOK pela sua URL real do webhook. Execute o script. Se você vir um código de status 204, a mensagem foi enviada com sucesso. Verifique seu canal do Discord para a mensagem de “Bot de Teste”.

O Que Fazer Se a Substituição de Nome de Usuário Não Aparecer

Se sua mensagem aparecer, mas usar o nome padrão do webhook em vez do seu nome personalizado, verifique estes pontos:

• Certifique-se de que o campo username está no nível superior do seu objeto JSON. Ele não pode estar aninhado dentro de outro campo.
• Verifique se o JSON é válido. Use uma ferramenta de validação JSON para verificar erros de sintaxe, como vírgulas ou aspas faltando.
• Garanta que a URL do webhook está correta e que você está enviando a requisição POST para a URL completa, incluindo o ID e token exclusivos no final.
• Confira se o nome de usuário não contém apenas espaços em branco ou caracteres de controle. O Discord exige pelo menos um caractere visível.

Agora você pode enviar mensagens de webhook com qualquer nome de usuário personalizado que escolher. Isso dá controle total sobre como as mensagens automatizadas aparecem nos seus canais do Discord. Para ir além, tente combinar a substituição de nome de usuário com avatares personalizados e rich embeds para um visual mais polido. Lembre-se de que a substituição só funciona para mensagens que incluam o campo username no payload JSON, então planeje seus scripts de acordo.