Como Enviar Mensagens de Webhook do Discord com Vários Embeds em um Único POST

Ao enviar uma mensagem para um webhook do Discord, você pode incluir um ou mais objetos embed para exibir conteúdo rico, como campos, imagens e barras laterais coloridas. Por padrão, uma única requisição POST pode conter até 10 embeds no array embeds. Isso é útil quando você deseja entregar várias informações em uma única mensagem sem enviar várias requisições separadas. Este artigo explica como estruturar o payload JSON para incluir múltiplos embeds em um único POST, quais são os limites de embed e como evitar erros comuns de formatação.

O que é um Embed de Webhook do Discord e como funciona?

Um webhook do Discord é uma forma simples de enviar mensagens automatizadas de aplicações externas para um canal de texto. Ao criar um webhook, você obtém uma URL única que aceita requisições HTTP POST com um payload JSON. O payload pode conter uma string content para texto simples e um array embeds para objetos embed ricos. Cada embed pode exibir um título, descrição, URL, cor, autor, rodapé, imagem, miniatura e até 25 campos. O número total de caracteres de todas as propriedades do embed combinadas não deve exceder 6000 caracteres por requisição. O número máximo de embeds por mensagem é 10. Se você exceder qualquer um desses limites, o Discord retorna um erro 400 Bad Request.

O objeto embed segue a especificação da API do Discord. Você deve usar JSON válido com os nomes de propriedade corretos. Por exemplo, a propriedade color aceita um valor inteiro decimal, não uma string hexadecimal. Para obter o valor decimal de uma cor hex, converta para base 10. Para uma cor vermelha hex #FF0000, o valor decimal é 16711680. Os campos do embed aparecem como linhas na mensagem e podem ser configurados para exibição inline ou empilhada. Ao enviar múltiplos embeds, cada um aparece como um bloco separado no canal, empilhados verticalmente.

Passos para Enviar um Webhook com Múltiplos Embeds em um Único POST

Prepare o Payload JSON

Crie um objeto JSON que inclua o array embeds. Cada item no array é um objeto embed separado. O exemplo a seguir mostra um payload com dois embeds. O primeiro embed tem título, descrição, cor e um campo. O segundo embed tem título, descrição e uma cor diferente.

{
  "embeds": [
    {
      "title": "Status do Servidor",
      "description": "Todos os sistemas estão operacionais.",
      "color": 3066993,
      "fields": [
        {
          "name": "Tempo de atividade",
          "value": "99,9%",
          "inline": true
        }
      ]
    },
    {
      "title": "Último Lançamento",
      "description": "A versão 2.0 já está disponível.",
      "color": 15277667
    }
  ]
}

Envie a Requisição POST

1. Copie a URL do webhook
   No Discord, vá em Configurações do Servidor > Integrações > Webhooks. Clique no nome do webhook e copie a URL. Ela se parece com https://discord.com/api/webhooks/123456789/abcdef.
2. Use curl para testar a requisição
   Abra um terminal e execute o seguinte comando. Substitua WEBHOOK_URL pela sua URL real.
   curl -H "Content-Type: application/json" -X POST -d '{"embeds":[{"title":"Primeiro","description":"Primeiro embed","color":3066993},{"title":"Segundo","description":"Segundo embed","color":15277667}]}' WEBHOOK_URL
3. Verifique o resultado no Discord
   Confira seu canal. Você deve ver dois blocos de embed empilhados verticalmente. Cada bloco mostra o título e a descrição que você forneceu.

Inclua uma Mensagem de Texto Simples Junto com os Embeds

Você pode enviar tanto uma string content quanto o array embeds no mesmo POST. O texto aparece acima dos embeds. Use isso para adicionar um ping ou um breve anúncio.

{
  "content": "@everyone Atualização do servidor disponível",
  "embeds": [
    {
      "title": "Notas da Atualização",
      "description": "Veja abaixo os detalhes.",
      "color": 15277667
    }
  ]
}

Use o Postman para um Teste Mais Visual

1. Crie uma nova requisição POST
   Insira a URL do seu webhook como URL da requisição.
2. Defina o cabeçalho Content-Type
   Adicione um cabeçalho com chave Content-Type e valor application/json.
3. Cole o payload JSON na aba Body
   Selecione raw e cole seu JSON que inclui o array embeds.
4. Envie a requisição
   Clique em Send. Uma resposta 204 No Content significa sucesso. Verifique o Discord para ver os embeds.

Erros Comuns e Limitações ao Enviar Múltiplos Embeds

Exceder o Limite de 10 Embeds

Se você incluir 11 ou mais objetos no array embeds, o Discord retorna um erro 400 Bad Request com uma mensagem sobre a contagem de embeds. Reduza o array para 10 ou menos. Se precisar de mais de 10 embeds, envie uma segunda requisição POST.

Contagem Total de Caracteres do Embed Acima de 6000

A contagem combinada de caracteres de todas as propriedades do embed em uma única requisição deve ser inferior a 6000. Isso inclui títulos, descrições, nomes de campos, valores de campos, texto do rodapé e nomes de autores. Se seu payload exceder esse limite, o Discord trunca ou rejeita a mensagem. Calcule o comprimento total antes de enviar. Use descrições curtas e limite os valores dos campos a 1024 caracteres cada.

Valor de Cor Incorreto

A propriedade color espera um inteiro decimal, não uma string hexadecimal. Por exemplo, use 15277667 em vez de "#E67E22". Para converter uma cor hex como #E67E22, calcule o valor decimal: 230 * 65536 + 126 * 256 + 34 = 15277667. Se você usar uma string, o Discord ignora a cor e usa o padrão de barra lateral cinza.

Campos Obrigatórios Ausentes para Cada Embed

Nenhuma propriedade é estritamente obrigatória em um objeto embed, mas pelo menos uma propriedade deve estar presente para que o embed seja renderizado. Se você incluir um objeto vazio {}, o Discord pode ainda mostrar um pequeno bloco vazio. Forneça pelo menos um title ou description para garantir que o embed seja exibido corretamente.

Array de Campos Excede 25 Itens

Cada embed pode ter no máximo 25 campos. Se você adicionar mais, o Discord ignora os campos extras. Planeje seus campos para caber dentro desse limite. Se precisar de mais campos, divida-os entre vários embeds.

Limites de Embed do Webhook do Discord: Único POST vs Múltiplos POSTs

Item	Único POST (até 10 embeds)	Múltiplos POSTs (mais de 10 embeds)
Máximo de embeds por requisição	10	Sem limite por canal, mas cada requisição limitada a 10
Limite total de caracteres por requisição	6000 (todos os embeds combinados)	6000 por requisição
Ordem das mensagens	Embeds aparecem na ordem do array, empilhados verticalmente	Cada POST cria uma mensagem separada; a ordem depende do horário de envio
Tratamento de limite de taxa	Uma requisição conta como uma chamada de API	Múltiplas requisições aumentam o uso do limite de taxa; respeite os cabeçalhos Retry-After
Melhor caso de uso	Entregar um conjunto de informações relacionadas em uma única mensagem	Registrar eventos separados ou lotes que precisam de timestamps individuais

Ao enviar múltiplos embeds em um único POST, todos os embeds pertencem à mesma mensagem e compartilham o mesmo timestamp. Se você precisar que cada embed tenha seu próprio timestamp, envie requisições POST separadas. Para a maioria dos casos de uso, como relatórios de status do servidor, notas de lançamento ou saída de comandos, um único POST com até 10 embeds é a abordagem mais eficiente.

Conclusão

Agora você pode enviar mensagens de webhook do Discord com múltiplos embeds a partir de uma única requisição POST, colocando cada objeto embed dentro do array embeds. Lembre-se de manter o número total de embeds em 10 ou menos e a contagem combinada de caracteres abaixo de 6000. Use valores inteiros decimais para a propriedade color e valide seu JSON com curl ou Postman antes de implantar. Para formatação mais avançada, explore as propriedades footer, image e thumbnail dentro de cada objeto embed para criar notificações mais ricas.