Como Enviar Arquivos via Webhook do Discord com Multipart Form Data Corretamente

Quando você envia uma mensagem para um webhook do Discord, pode anexar arquivos diretamente, em vez de apenas postar texto ou URLs. Muitos desenvolvedores tentam usar payloads JSON simples e depois se perguntam por que seus anexos falham ou aparecem como links quebrados. A abordagem correta exige o uso da codificação multipart/form-data, que permite incluir tanto os dados binários do arquivo quanto o payload JSON em uma única requisição HTTP. Este artigo explica exatamente como estruturar essa requisição multipart, quais campos são necessários e como evitar as armadilhas comuns que fazem o Discord rejeitar o upload.

O Que É Multipart Form Data e Por Que o Discord Exige Isso

Os webhooks do Discord aceitam dois tipos de requisições: um POST JSON simples e um POST multipart/form-data. O método JSON funciona apenas para mensagens baseadas em texto, embeds e nomes de usuário. Quando você deseja anexar um arquivo como uma imagem, PDF ou arquivo ZIP, deve mudar para multipart/form-data. Essa codificação permite que a requisição HTTP contenha várias partes, cada uma com seu próprio tipo de conteúdo e cabeçalhos. Uma parte contém o payload JSON que define a mensagem, e outras partes contêm os dados binários reais do arquivo. O Discord lê o campo payload_json para obter os metadados da mensagem e então associa quaisquer campos file a essa mensagem. Sem a codificação multipart, os dados do arquivo seriam interpretados como parte do corpo JSON, o que quebraria a requisição e retornaria um erro 400 Bad Request.

Como o Discord Processa a Requisição Multipart

Quando o Discord recebe uma requisição multipart, ele analisa cada parte sequencialmente. A parte payload_json deve aparecer primeiro. Dentro desse JSON, você pode definir propriedades como content, embeds, username e avatar_url. Você também pode incluir um array attachments que lista metadados para cada arquivo que está enviando. Cada entrada no array attachments deve ter um campo id que corresponda ao índice da parte do campo file correspondente, começando em 0. O campo filename nos metadados do anexo informa ao Discord qual nome exibir para o arquivo enviado. Se você omitir o array attachments, o Discord ainda anexará o arquivo, mas usará o nome de arquivo original do cabeçalho Content-Disposition da parte do arquivo.

Passos para Enviar um Arquivo via Webhook do Discord Usando Multipart Form Data

Os passos a seguir assumem que você tem uma URL de webhook de um canal do Discord. Você pode obter uma acessando Configurações do Servidor > Integrações > Webhooks e criando um novo webhook. Os passos mostram como enviar um único arquivo de imagem com uma mensagem de texto usando um cliente HTTP padrão como cURL ou uma biblioteca de linguagem de programação.

1. Prepare o payload JSON
   Crie um objeto JSON que contenha o texto da mensagem e, opcionalmente, um array attachments. Para um único arquivo, defina o array como [{'id': 0, 'filename': 'exemplo.png'}]. O id deve corresponder ao índice da parte file que você enviará depois. O filename pode ser qualquer nome que você queira que o Discord exiba.
2. Defina o boundary multipart
   Escolha uma string única que não apareça nos dados do arquivo. Uma abordagem comum é usar um UUID aleatório ou um timestamp. Por exemplo, ----WebKitFormBoundary7MA4YWxkTrZu0gW. Esse boundary deve ser colocado no cabeçalho Content-Type da requisição HTTP.
3. Escreva as partes do corpo da requisição
   Comece com a string boundary prefixada por dois traços. Em seguida, adicione o cabeçalho Content-Disposition para a parte JSON: Content-Disposition: form-data; name='payload_json'. Siga com uma linha em branco e depois a string JSON. Depois disso, adicione o boundary novamente e, em seguida, o Content-Disposition para a parte do arquivo: Content-Disposition: form-data; name='file'; filename='exemplo.png'. Inclua o cabeçalho Content-Type para o arquivo, como image/png. Adicione uma linha em branco e depois os dados binários brutos do arquivo. Termine o corpo com a string boundary prefixada por dois traços e sufixada por dois traços.
4. Defina os cabeçalhos HTTP
   Inclua Content-Type: multipart/form-data; boundary=SEU_BOUNDARY nos cabeçalhos da requisição. Não defina Content-Type: application/json, pois isso informaria ao Discord para esperar um corpo JSON em vez de dados multipart.
5. Envie a requisição POST
   Use o método POST para enviar a requisição para sua URL de webhook. Se estiver usando cURL, o comando se parece com: curl -X POST -H 'Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' --data-binary @request.txt https://discord.com/api/webhooks/123456/abc onde request.txt contém o corpo multipart completo conforme descrito.

Erros Comuns e Como Evitá-los

Mesmo com a estrutura multipart correta, vários problemas podem fazer o webhook falhar. Abaixo estão os problemas mais frequentes e suas soluções.

Arquivo Aparece como Anexo Vazio ou Link Quebrado

Isso geralmente acontece quando o array attachments no payload JSON está ausente ou tem valores de id incorretos. O Discord usa o id para corresponder a parte do arquivo aos metadados do anexo. Se o id for 0, mas você enviou a parte do arquivo como a terceira parte em vez da segunda, o Discord não consegue vinculá-los. Sempre envie a parte JSON primeiro, depois as partes do arquivo em ordem, e defina id como 0 para o primeiro arquivo, 1 para o segundo, e assim por diante. Também garanta que o filename no JSON corresponda ao nome do arquivo no cabeçalho Content-Disposition da parte do arquivo.

Discord Retorna 400 Bad Request com ‘Unsupported Media Type’

Esse erro significa que o cabeçalho Content-Type está errado ou está faltando o parâmetro boundary. Verifique se a string boundary é exatamente a mesma no cabeçalho e no corpo. Também verifique se o boundary no corpo é prefixado com dois traços (--) e se o boundary de fechamento tem dois traços no final. Alguns clientes HTTP adicionam automaticamente cabeçalhos extras que sobrescrevem seu Content-Type. Nesse caso, defina o cabeçalho explicitamente e desative qualquer codificação automática.

Tamanho do Arquivo Excede o Limite do Discord

Os webhooks do Discord têm um limite de tamanho de arquivo que depende do nível de Boost do servidor. Para um servidor gratuito, o limite é de 8 MB por arquivo. Para servidores com Boost, pode ser de até 50 MB. Se seu arquivo for maior, você deve comprimi-lo ou dividi-lo em várias partes. O Discord retornará um erro 413 Payload Too Large se o arquivo exceder o limite. Verifique o limite de upload atual do servidor antes de enviar.

Vários Arquivos São Enviados, mas Apenas Um Aparece

Ao enviar vários arquivos, cada arquivo deve ter seu próprio campo file com um atributo name único no cabeçalho Content-Disposition. Você pode usar file para todos eles, mas o array attachments deve listar cada arquivo com um id distinto. A ordem das partes do arquivo no corpo deve corresponder à ordem dos valores de id. Se você enviar partes do arquivo fora de ordem, o Discord as mapeará incorretamente.

Métodos de Upload de Arquivo do Webhook do Discord: Multipart vs Apenas JSON

Item	Multipart Form Data	Apenas JSON
Suporte a anexo de arquivo	Sim, qualquer tipo de arquivo até o limite de tamanho	Não, apenas embeds de imagens baseados em URL
Conteúdo da mensagem	Suportado via campo payload_json	Suportado via corpo JSON
Suporte a embeds	Suportado dentro de payload_json	Suportado diretamente no JSON
Personalização de nome de usuário	Suportado dentro de payload_json	Suportado diretamente no JSON
Método HTTP	Apenas POST	Apenas POST
Cabeçalho obrigatório	Content-Type: multipart/form-data; boundary=...	Content-Type: application/json

Agora você pode enviar arquivos para qualquer webhook do Discord usando a estrutura correta de multipart form data. Comece criando um pequeno script de teste com cURL ou sua linguagem de programação preferida para verificar se o payload JSON e as partes do arquivo estão na ordem correta. Lembre-se de que o campo payload_json deve sempre vir primeiro, seguido por cada arquivo em sequência. Se precisar enviar vários arquivos, incremente os valores de id no array attachments e mantenha as partes do arquivo na mesma ordem. Para casos de uso avançados, explore as propriedades allowed_mentions e flags dentro do payload JSON para controlar como o Discord lida com a mensagem.