Por que a substituição do nome de usuário do webhook do Discord é revertida após tentar editar

Você edita uma mensagem de webhook do Discord para alterar o nome de usuário, mas após salvar, o nome volta ao padrão do webhook. Isso acontece porque o Discord trata a substituição do nome de usuário como um atributo único aplicado apenas no envio inicial. O sistema de webhook não permite alterações retroativas no nome exibido após a mensagem existir. Este artigo explica o motivo técnico exato desse comportamento e mostra o fluxo de trabalho correto para definir um nome de usuário personalizado antes de enviar uma mensagem de webhook.

Por que a substituição do nome de usuário do webhook do Discord é revertida ao editar

Os webhooks do Discord operam com uma regra simples: a substituição do nome de usuário é uma propriedade do evento de criação da mensagem, não uma propriedade da mensagem em si. Quando você envia uma mensagem de webhook usando a API do Discord ou uma biblioteca de bot, você inclui um campo username no payload JSON. O Discord lê esse campo uma vez, aplica-o à exibição da mensagem e o descarta. O objeto de mensagem armazenado nos servidores do Discord não retém o campo username como um atributo mutável.

Quando você edita uma mensagem de webhook pelo cliente do Discord (clique direito > Editar Mensagem) ou pelo endpoint de edição da API, o corpo da requisição pode modificar apenas os campos content, embeds, components e attachments. Os campos username e avatar_url não fazem parte do esquema de edição. A API ignora silenciosamente qualquer valor de username enviado em uma requisição de edição. O nome exibido então volta ao nome padrão do webhook, que é definido na página de configurações do webhook.

Esse design impede abusos onde um ator malicioso poderia alterar o nome exibido de uma mensagem depois que ela foi vista pelos usuários. Também simplifica a lógica de edição de mensagens para desenvolvedores. A substituição do nome de usuário é intencionalmente de gravação única.

Passos para definir um nome de usuário personalizado no webhook antes de enviar uma mensagem

Para exibir um nome de usuário personalizado com uma mensagem de webhook, você deve definir o campo username no momento em que cria a mensagem. As instruções a seguir cobrem tanto o método pelo cliente do Discord quanto o método pela API.

Método 1: Criar uma mensagem de webhook com nome de usuário personalizado usando o cliente do Discord

1. Abra as Configurações do Servidor
   Clique com o botão direito no ícone do servidor na barra lateral esquerda e selecione Configurações do Servidor. Se estiver no celular, toque no menu de três pontos ao lado do nome do servidor e escolha Configurações.
2. Vá para Integrações
   No menu à esquerda, clique em Integrações. Na seção Webhooks, clique em Ver Webhooks.
3. Selecione o webhook desejado
   Clique no webhook que você quer usar. No pop-up, você verá campos para Nome (o nome padrão), Canal e um botão Copiar URL do Webhook.
4. Envie uma mensagem com um nome personalizado
   O cliente do Discord não fornece uma interface nativa para definir um nome de usuário personalizado por mensagem. Você deve usar uma ferramenta de terceiros ou um bot que suporte a API de webhook. Por exemplo, use um serviço como Discohook ou um script personalizado. Cole a URL do webhook na ferramenta, defina o campo Nome de Usuário para a substituição desejada, escreva o conteúdo da mensagem e clique em Enviar.

Método 2: Definir a substituição do nome de usuário via API do Discord

1. Obtenha a URL do webhook
   Em Configurações do Servidor > Integrações > Webhooks, clique no webhook e depois em Copiar URL do Webhook. O formato da URL é https://discord.com/api/webhooks/{webhook_id}/{token}.
2. Envie uma requisição POST com o campo username
   Use uma ferramenta como curl, Postman ou uma linguagem de programação de sua escolha. Envie uma requisição POST para a URL do webhook com um corpo JSON contendo os campos username e content. Exemplo de comando curl:
   curl -X POST "https://discord.com/api/webhooks/123456789/abc123def456" -H "Content-Type: application/json" -d '{"username":"Meu Nome Personalizado","content":"Olá do meu webhook!"}'
3. Verifique a exibição
   Confira o canal de destino. A mensagem exibirá o nome de usuário que você definiu no campo username. O avatar será o padrão do webhook, a menos que você também inclua o campo avatar_url.

Se a substituição do nome de usuário do webhook ainda não funcionar

Se você seguiu os passos acima, mas o nome de usuário ainda reverte, verifique estes problemas comuns.

Você editou uma mensagem que já existia

Como explicado, editar uma mensagem de webhook existente não pode alterar o nome de usuário. Você deve excluir a mensagem antiga e enviar uma nova com o nome de usuário desejado. Use o endpoint DELETE /webhooks/{id}/{token}/messages/{message_id} da API para remover a mensagem e depois envie uma nova requisição POST.

Você definiu o nome de usuário nas configurações do webhook em vez do payload da mensagem

O campo Nome na página de configurações do webhook define o nome padrão que aparece quando nenhuma substituição de nome de usuário é fornecida. Alterar esse nome padrão afeta todas as mensagens futuras que não incluam um campo username. Não afeta mensagens que já possuem uma substituição de nome de usuário. Para alterar o nome exibido de uma mensagem existente, você deve reenviá-la com um novo valor de username.

Sua biblioteca de bot não suporta substituição de nome de usuário na edição

Algumas bibliotecas de bot expõem um método como edit_message() que aceita um parâmetro username. A biblioteca pode enviar esse parâmetro na chamada da API, mas a API do Discord o ignora. Verifique a documentação da sua biblioteca para confirmar se o método de edição não alega suportar alterações de nome de usuário. Se alegar, a biblioteca pode estar enviando o campo incorretamente ou confiando em uma versão desatualizada da API.

Propriedades da mensagem de webhook do Discord: criação vs edição

Propriedade	Criação (POST)	Edição (PATCH)
username	Aceito, define nome exibido	Ignorado
avatar_url	Aceito, define avatar	Ignorado
content	Aceito	Aceito
embeds	Aceito	Aceito
components	Aceito	Aceito
attachments	Aceito	Aceito

A tabela acima mostra que username e avatar_url são campos de gravação única. Você não pode alterá-los após a mensagem ser criada. Para atualizar o nome exibido, você deve excluir a mensagem original e reenviá-la com a nova substituição.

Agora você sabe que a substituição do nome de usuário é um atributo do momento da criação. Para alterá-lo, exclua a mensagem existente e envie uma nova com o campo username correto. Se você está construindo um bot que precisa atualizar nomes regularmente, considere armazenar um mapeamento de IDs de mensagem para nomes de usuário desejados e reenviar automaticamente as mensagens quando o nome mudar. Essa abordagem evita confusão e garante que o nome correto apareça sempre.