Como Enviar Mensagens de Webhook do Discord com Lista de Menções Permitidas

Ao enviar mensagens por um webhook do Discord, você pode mencionar @everyone, @here, cargos ou usuários individuais. Por padrão, um webhook pode mencionar qualquer um desses alvos. Isso pode causar notificações indesejadas se um webhook for mal utilizado ou enviar uma mensagem que marque um grupo grande por engano. A lista de menções permitidas (allowed mentions whitelist) permite restringir quais menções o webhook pode realmente disparar. Este artigo explica como configurar o objeto allowed_mentions no payload do webhook para que apenas cargos ou usuários aprovados possam ser mencionados.

Webhooks do Discord são ferramentas poderosas para integrar serviços externos como GitHub, Jenkins ou bots personalizados ao seu servidor. Sem controles adequados, um único webhook mal configurado pode notificar centenas de membros. A lista de menções permitidas resolve isso permitindo que você defina exatamente quais cargos, usuários ou menções de grupo (@everyone, @here) o webhook pode usar. Qualquer menção fora da lista é ignorada silenciosamente pelo Discord. Este guia aborda a estrutura JSON, exemplos práticos de código e armadilhas comuns.

O que a Lista de Menções Permitidas Faz

O objeto allowed_mentions é uma propriedade JSON que você inclui no corpo de uma requisição POST do webhook. Ele controla como o Discord lida com menções que aparecem no conteúdo da mensagem. Sem esse objeto, um webhook pode mencionar qualquer cargo, usuário ou as menções de grupo especiais @everyone e @here. Com a lista de permissões, você restringe quais menções realmente produzem uma notificação.

O objeto tem três propriedades principais:

parse: Um array que pode conter as strings “everyone”, “here” e “roles”. Se você incluir “everyone”, o webhook pode mencionar @everyone. Se incluir “roles”, o webhook pode mencionar qualquer cargo pelo nome ou ID. Para desabilitar todas as menções de grupo, defina parse como um array vazio [].

roles: Um array de IDs de cargos (strings) que o webhook pode mencionar. Se você incluir um ID de cargo aqui, o webhook pode mencionar esse cargo mesmo que parse não contenha “roles”. Se deixar este array vazio, nenhuma menção de cargo é permitida, a menos que parse inclua “roles”.

users: Um array de IDs de usuários (strings) que o webhook pode mencionar. Se você incluir um ID de usuário aqui, o webhook pode mencionar esse usuário. Se deixar este array vazio, nenhuma menção de usuário é permitida, a menos que parse inclua “everyone” ou “here”.

A lista de permissões funciona por prioridade: os arrays roles e users substituem o array parse para esses IDs específicos. Por exemplo, se parse for [“everyone”, “here”, “roles”] mas o array roles estiver vazio, o webhook ainda pode mencionar @everyone e @here, mas não pode mencionar nenhum cargo. Se você quiser permitir apenas certos cargos e nenhuma menção de grupo, defina parse como um array vazio e preencha o array roles com os IDs de cargos específicos.

Como Enviar uma Mensagem de Webhook com a Lista de Menções Permitidas

Você envia uma mensagem de webhook fazendo uma requisição HTTP POST para a URL do webhook fornecida pelo Discord. O corpo da requisição deve ser JSON. Abaixo estão as etapas para configurar o objeto allowed_mentions nesse payload JSON.

1. Obter a URL do webhook
   No seu servidor Discord, vá em Configurações do Servidor > Integrações > Webhooks. Clique no webhook que deseja usar ou crie um novo. Copie a URL do webhook. Ela se parece com https://discord.com/api/webhooks/123456/abcdef.
2. Construir o payload JSON
   Crie um objeto JSON com um campo content contendo sua mensagem. Adicione um objeto allowed_mentions como campo irmão. Exemplo:
   { "content": "Olá <@&123456789> e <@987654321>", "allowed_mentions": { "parse": [], "roles": ["123456789"], "users": ["987654321"] } }
   Neste exemplo, o ID de cargo 123456789 e o ID de usuário 987654321 estão na lista de permissões. O array parse está vazio, então @everyone e @here estão bloqueados.
3. Enviar a requisição POST
   Use qualquer cliente HTTP: cURL, Postman ou sua linguagem de programação preferida. Defina o cabeçalho Content-Type como application/json. Envie o payload JSON para a URL do webhook. Exemplo de comando cURL:
   curl -X POST -H "Content-Type: application/json" -d '{"content":"Olá <@&123456789>","allowed_mentions":{"parse":[],"roles":["123456789"]}}' https://discord.com/api/webhooks/123456/abcdef
4. Verificar o resultado
   Confira seu servidor Discord. A mensagem do webhook deve aparecer. Se o alvo da menção estiver na lista de permissões, a menção será destacada e disparará uma notificação. Se o alvo da menção não estiver na lista, o texto aparecerá como texto simples sem notificação.

Você também pode enviar embeds com webhooks. O objeto allowed_mentions funciona da mesma forma — coloque-o no nível superior do JSON, não dentro do objeto embed. Exemplo com embed:

{
  "embeds": [{
    "title": "Deploy Concluído",
    "description": "Nova versão implantada por <@123456789>"
  }],
  "allowed_mentions": {
    "parse": [],
    "users": ["123456789"]
  }
}

Erros Comuns com a Lista de Menções Permitidas

Menção Ainda Dispara Notificação Mesmo com Array parse Vazio

Se você definir parse como um array vazio, mas os arrays roles ou users contiverem o ID do alvo, a menção ainda funcionará. Isso é proposital — os arrays roles e users substituem parse para esses IDs específicos. Para bloquear completamente todas as menções, defina parse como um array vazio e também defina roles e users como arrays vazios ou omita-os completamente.

Usar Nomes de Cargo em Vez de IDs de Cargo

O array roles deve conter IDs de cargo, não nomes de cargo. IDs de cargo são strings numéricas. Você pode obter um ID de cargo ativando o Modo Desenvolvedor nas Configurações de Usuário do Discord > Avançado > Modo Desenvolvedor, depois clicando com o botão direito no cargo em Configurações do Servidor > Cargos e selecionando Copiar ID. Se você usar um nome de cargo, o Discord o ignora e a menção é suprimida.

Esquecer de Incluir o Objeto allowed_mentions em Embeds

O objeto allowed_mentions se aplica a toda a mensagem do webhook, incluindo todos os embeds. Você não precisa repeti-lo dentro de cada embed. No entanto, se sua mensagem contiver tanto conteúdo quanto embeds, o objeto allowed_mentions deve estar no nível superior. Se você colocá-lo dentro de um objeto embed, o Discord o ignora.

Webhook Não Tem Permissão para Mencionar o Cargo

Mesmo que você coloque um ID de cargo na lista de permissões, o webhook deve ter a permissão “Mencionar @everyone, @here e Todos os Cargos” no canal onde a mensagem é enviada. Essa permissão é concedida por padrão a webhooks criados por administradores. Se o webhook não tiver essa permissão, a menção é suprimida independentemente da lista de permissões.

Configuração	Efeito em @everyone	Efeito em Menções de Cargo
Nenhum objeto allowed_mentions	Permitido	Permitido
parse: [“everyone”, “roles”]	Permitido	Permitido
parse: []	Bloqueado	Bloqueado
parse: [], roles: [“123”]	Bloqueado	Apenas cargo ID 123 permitido
parse: [“everyone”], roles: []	Permitido	Bloqueado

A lista de menções permitidas oferece controle granular sobre as notificações do webhook. Combinando os arrays parse, roles e users, você pode permitir apenas cargos ou usuários específicos enquanto bloqueia @everyone e @here. Sempre teste seu payload com um público pequeno antes de implantar em canais de produção. Use IDs de cargo em vez de nomes e verifique se o webhook tem as permissões necessárias no canal de destino.