Como Criar um Webhook do Discord com Avatar Personalizado por Mensagem

Webhooks do Discord permitem enviar mensagens automatizadas para um canal de texto sem usar um bot completo. Por padrão, um webhook usa um nome e avatar fixos definidos na criação. Mas você pode querer que cada mensagem mostre um nome de usuário e foto de perfil diferentes, como para um bot de anúncios de múltiplas marcas ou um sistema de roleplay. Este artigo explica como construir um webhook do Discord que envia cada mensagem com avatar e nome de usuário personalizados usando a API de webhook. Você aprenderá a estrutura do payload, as permissões necessárias e como testar o webhook com curl ou um script simples.

Como os Webhooks do Discord Lidam com Avatares

Um webhook do Discord é um endpoint HTTP simples que aceita payloads JSON. Quando você cria um webhook em um canal, o Discord atribui a ele um nome e avatar padrão. Você pode alterar esses padrões nas configurações do webhook, mas isso muda a identidade para todas as mensagens enviadas por meio desse webhook.

A API de webhook, no entanto, suporta dois campos opcionais no corpo JSON: username e avatar_url. Quando você inclui esses campos em uma única requisição POST, o Discord exibe essa mensagem com o nome de usuário e imagem de avatar especificados. O webhook mantém seus padrões originais para a próxima mensagem. Essa substituição por mensagem é o recurso principal que você precisa para construir um webhook que envia cada mensagem com um avatar personalizado.

O avatar_url deve apontar para um arquivo de imagem publicamente acessível. O Discord aceita formatos JPEG, PNG, GIF e WebP. A imagem não precisa estar hospedada em um serviço específico, mas deve ser acessível pelos servidores do Discord. O campo username aceita uma string de até 32 caracteres. Se você omitir qualquer um dos campos, o Discord usa o padrão do webhook.

Pré-requisitos

Antes de começar, você precisa de um servidor Discord onde tenha a permissão Gerenciar Webhooks. Essa permissão é concedida por padrão a administradores do servidor e a cargos com a permissão Gerenciar Servidor. Você também precisa de uma ferramenta para enviar requisições HTTP POST. Pode usar curl, Postman ou uma linguagem de programação como Python ou JavaScript.

Passos para Criar um Webhook do Discord com Avatares Personalizados por Mensagem

1. Abra as Configurações do Servidor e Crie um Webhook
   Abra o Discord e navegue até seu servidor. Clique no nome do servidor no canto superior esquerdo e selecione Configurações do Servidor no menu suspenso. Na barra lateral esquerda, clique em Integrações. Em Webhooks, clique em Criar Webhook. Dê um nome e escolha o canal de destino. Clique em Copiar URL do Webhook e salve-a com segurança. Você não precisa definir um avatar personalizado aqui, a menos que queira um fallback.
2. Prepare Suas Imagens de Avatar Personalizadas
   Faça upload de cada imagem de avatar para um serviço de hospedagem público. O Discord não hospeda imagens para você, então você precisa de uma URL que termine com uma extensão de imagem. Serviços como Imgur, Cloudinary ou seu próprio servidor web funcionam. Copie a URL direta da imagem para cada avatar que planeja usar. Certifique-se de que a URL não exija autenticação.
3. Construa o Payload JSON
   Crie um objeto JSON com pelo menos o campo content para o texto da mensagem. Adicione o campo username com o nome de exibição desejado para esta mensagem. Adicione o campo avatar_url com a URL direta da imagem. Um payload completo se parece com isso:
   {
"content": "Olá de um avatar personalizado!",
"username": "Bot Assistente",
"avatar_url": "https://exemplo.com/avatar.png"
}
4. Envie a Requisição POST Usando curl
   Abra um terminal e execute o seguinte comando, substituindo URL_DO_WEBHOOK pela URL copiada e o JSON pelo seu payload:
   curl -X POST -H "Content-Type: application/json" -d '{"content":"Olá de um avatar personalizado!","username":"Bot Assistente","avatar_url":"https://exemplo.com/avatar.png"}' URL_DO_WEBHOOK
   Pressione Enter. Se bem-sucedido, o Discord retorna um status 204 No Content e a mensagem aparece no canal com seu avatar e nome de usuário personalizados.
5. Envie Múltiplas Mensagens com Avatares Diferentes
   Repita o passo 4 com um username e avatar_url diferentes para cada mensagem. Cada requisição é independente. Você pode automatizar isso com um script que percorre uma lista de usuários e avatares.

Automatize com um Script Python

Para uso repetido, escreva um pequeno script Python. Instale a biblioteca requests com pip install requests. Em seguida, use o seguinte código:

import requests

webhook_url = "SUA_URL_DO_WEBHOOK"

payload = {
    "content": "Esta mensagem tem um avatar personalizado!",
    "username": "Usuário Personalizado",
    "avatar_url": "https://exemplo.com/avatar.png"
}

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

Execute o script. A mensagem aparece no canal. Altere os valores de username e avatar_url no dicionário para enviar avatares diferentes.

Se o Avatar Personalizado Não Aparecer

URL do Avatar Retorna 404 ou Redirecionamento

O Discord exige uma URL de imagem direta que retorne um status 200 e um tipo MIME de imagem. Se a URL redirecionar ou exigir login, o Discord ignora o campo avatar_url e usa o padrão do webhook. Teste a URL em um navegador. Se redirecionar, use a URL de destino final. Se a imagem estiver no Imgur, use o link direto terminando em .png ou .jpg.

Cabeçalho Content-Type Ausente ou Incorreto

O cabeçalho Content-Type deve ser application/json. Se você enviar o payload como dados de formulário ou omitir o cabeçalho, o Discord ignora os campos username e avatar_url. Sempre defina o cabeçalho explicitamente em sua requisição.

URL do Webhook Inválida ou Expirada

URLs de webhook não expiram, mas podem ser excluídas ou regeneradas. Se você receber uma resposta 404, o webhook pode ter sido excluído. Volte para Configurações do Servidor > Integrações e confirme se o webhook ainda existe. Se não, crie um novo.

Campos do Payload do Webhook do Discord: Fixos vs. Por Mensagem

Campo	Padrão do Webhook (Fixo)	Substituição por Mensagem
Nome de Usuário	Definido na criação ou edição do webhook	Definido no payload JSON com o campo username
Avatar	Definido na criação ou edição do webhook	Definido no payload JSON com o campo avatar_url
Conteúdo	Não aplicável	Definido no payload JSON com o campo content
Embeds	Não aplicável	Definido no payload JSON com o array embeds

Esta tabela mostra quais campos são controlados pela configuração do webhook e quais podem ser substituídos por mensagem. Apenas username e avatar_url suportam substituições por mensagem. Todos os outros campos, como o canal de destino, são fixos.

Agora você pode construir um webhook do Discord que envia cada mensagem com um avatar e nome de usuário personalizados. Use os campos JSON username e avatar_url em cada requisição POST. Para automação, escreva um script que percorra uma lista de avatares e nomes. Lembre-se de que a URL do avatar deve ser um link de imagem direto e público. Teste seu payload com curl antes de integrá-lo a um sistema maior. Para uso avançado, adicione embeds ao seu payload para incluir conteúdo rico junto com o avatar personalizado.