---
title: "Enviar imagem, áudio e PDF pela API de WhatsApp | D-API"
description: "Como enviar imagem, áudio de voz, vídeo, documento e álbum pela API de WhatsApp, quando usar URL ou base64 e como baixar a mídia que o cliente manda para você."
url: https://d-api.cloud/api-whatsapp-enviar-midia
---

Guia da API de WhatsApp

# Como enviar imagem, áudio, vídeo e documento pela API de WhatsApp

Cada tipo de mídia tem um endpoint próprio, e todos seguem a mesma lógica: você informa a conexão, o número e o arquivo, por URL pública ou base64. Para receber, a mídia que o cliente manda chega pelo webhook e pode ser baixada pela API.

Por Time de engenharia D-APIAtualizado em 24 de set de 20265 min de leitura

## Por que mídia muda o resultado da conversa

Um boleto em PDF resolve mais do que um link para ele. A foto do produto vende melhor que a descrição. Um áudio curto do vendedor soa mais próximo que três parágrafos. Em sistemas de gestão, o comprovante que o cliente fotografa e manda de volta precisa chegar ao financeiro sem ninguém baixar e subir arquivo na mão.

Uma [API de WhatsApp](https://d-api.cloud/) trata os dois sentidos: seu sistema anexa arquivos nas mensagens que envia e recebe os arquivos que os clientes mandam, já prontos para salvar ou processar.

## Endpoints de envio por tipo de mídia

| Tipo | Endpoint | Campo do arquivo | Opcionais úteis |
| --- | --- | --- | --- |
| Imagem | `/messages/send/image` | `image` | `caption` |
| Áudio | `/messages/send/audio` | `audio` | `ptt` (mensagem de voz) |
| Vídeo | `/messages/send/video` | `video` | `caption`, `ptv`, `gifPlayback` |
| Documento | `/messages/send/document` | `document` | `fileName`, `mimetype` |
| Álbum | `/messages/send/album` | `media` (lista) | `caption` por item |
| Figurinha | `/messages/send/sticker` | `sticker` | \- |

Todas as rotas ficam em `https://api.d-api.cloud/api/v1` e exigem `sessionId` e `to`, com o número no formato internacional sem sinal de mais, como `5511999999999`.

## Exemplos de envio

### Documento com nome amigável

```
curl -X POST https://api.d-api.cloud/api/v1/messages/send/document \
  -H "Authorization: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "financeiro",
    "to": "5511999999999",
    "document": "https://arquivos.suaempresa.com/faturas/8812.pdf",
    "fileName": "fatura-setembro.pdf",
    "mimetype": "application/pdf"
  }'
```

Sem `fileName`, o cliente vê um nome genérico e desconfia. É um detalhe pequeno que reduz a pergunta "isso é golpe?" no atendimento.

### Imagem, voz e álbum com o SDK de Node

```
import { DApi } from 'd-api-sdk'

const dapi = new DApi({ apiKey: process.env.DAPI_KEY })

await dapi.messages.sendImage({
  sessionId: 'loja',
  to: '5511999999999',
  image: 'https://cdn.suaempresa.com/produtos/tenis-azul.jpg',
  caption: 'Chegou no seu tamanho. Quer que eu separe?',
})

await dapi.messages.sendAudio({
  sessionId: 'loja',
  to: '5511999999999',
  audio: 'https://cdn.suaempresa.com/audios/boas-vindas.ogg',
  ptt: true,
})

await dapi.messages.sendAlbum({
  sessionId: 'loja',
  to: '5511999999999',
  media: [
    { type: 'image', url: 'https://cdn.suaempresa.com/produtos/frente.jpg', caption: 'Frente' },
    { type: 'image', url: 'https://cdn.suaempresa.com/produtos/lateral.jpg', caption: 'Lateral' },
  ],
})
```

O SDK é um cliente fino sobre a mesma API REST, então tudo acima também funciona com qualquer cliente HTTP. Mais detalhes na página do [SDK de Node.js](https://d-api.cloud/integrations/nodejs-sdk).

## URL pública ou base64: como decidir

Nos envios individuais, o campo do arquivo aceita dois formatos, e cada um tem seu lugar. No álbum, os itens vão sempre por URL.

-   **URL pública:** o arquivo fica num storage ou CDN e você passa o link. A requisição fica leve, o mesmo arquivo serve para vários destinatários e você não trafega megabytes a cada chamada. O link precisa responder sem login e sem redirecionar para uma página de autenticação.
-   **Base64:** o conteúdo vai dentro do JSON. Faz sentido para arquivos gerados na hora, como um recibo montado pelo sistema, ou quando o documento tem dado sensível e você não quer deixá-lo num link acessível. O custo é um payload maior.

Se optar por URL com dado sensível, use links assinados com expiração curta. A API só precisa buscar o arquivo no momento do envio.

## Receber e baixar a mídia que o cliente envia

Quando o cliente manda foto, áudio ou documento, o evento `messages.received` chega no seu [webhook](https://d-api.cloud/webhook-api-whatsapp) com `type` igual a `image`, `audio`, `video`, `document` ou `sticker`. O `media_url` normalmente já traz um link do arquivo armazenado, e `media_data` traz tipo, tamanho, legenda, duração e, em áudio, se é mensagem de voz.

Se você precisa do conteúdo em base64 (para mandar a um OCR ou a um modelo de transcrição, por exemplo) ou o link não veio preenchido, use o download. O WhatsApp entrega a mídia criptografada, e o endpoint decifra usando os metadados que vieram no evento:

```
curl -X POST https://api.d-api.cloud/api/v1/media/download \
  -H "Authorization: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "financeiro",
    "direct_path": "<do webhook>",
    "media_key": "<do webhook>",
    "mimetype": "image/jpeg",
    "base64": true
  }'
```

Sem `base64: true`, o arquivo é salvo em storage e a resposta devolve `media_url`. Para arquivos grandes, o parâmetro `async` faz o download em segundo plano. Quem quer guardar tudo no próprio bucket pode usar a integração nativa com S3 ou MinIO.

## Erros comuns ao enviar mídia

-   **Link que exige login ou expira rápido demais:** o envio falha ou chega vazio. Teste a URL numa aba anônima.
-   **Áudio sem `ptt` quando a ideia era parecer voz:** o cliente recebe um arquivo, não um recado.
-   **Mandar a mesma mídia pesada em lote para muita gente:** além do custo de banda, volume atípico de envio é um dos sinais que levam a bloqueio. Leia [como evitar banimento](https://d-api.cloud/como-evitar-banimento-api-whatsapp) antes de automatizar campanhas.
-   **Processar a mídia antes de responder o webhook:** baixe e trate o arquivo num worker, depois de devolver 200.

Se você quer disparar mídia a partir de gatilhos do seu sistema sem escrever código, veja a [API de WhatsApp para automação](https://d-api.cloud/api-whatsapp-para-automacao). Para combinar mídia com opções clicáveis, continue em [botões e listas](https://d-api.cloud/api-whatsapp-botoes-e-listas).

## Perguntas frequentes

### Posso enviar um PDF pela API de WhatsApp?

Sim. Use o envio de documento, passando o arquivo por URL pública ou base64. Informe fileName para o cliente ver um nome legível, como boleto-marco.pdf, e mimetype quando o tipo não for óbvio pela extensão.

### Como fazer o áudio chegar como mensagem de voz gravada?

Envie com ptt igual a true. Sem esse campo, o arquivo aparece como áudio anexado, com player de arquivo. Com ptt, aparece como a bolinha de voz, igual a um áudio gravado na hora.

### É melhor mandar a mídia por URL ou em base64?

URL pública costuma ser o melhor caminho: o corpo da requisição fica pequeno e o mesmo arquivo serve para vários envios. Base64 faz sentido quando o arquivo é gerado na hora e não pode ficar exposto num link.

### Como recebo as fotos e áudios que o cliente me envia?

Eles chegam no webhook de mensagem recebida, com o tipo da mídia e, normalmente, um link já pronto em media\_url. Quando precisar do arquivo em base64 ou o link não vier preenchido, use o endpoint de download de mídia com os metadados do evento.

### Dá para mandar várias fotos numa mensagem só?

Sim, com o envio de álbum. Você passa uma lista de imagens e vídeos por URL, cada um com legenda opcional, e o WhatsApp mostra tudo agrupado, como quando alguém seleciona várias fotos da galeria.

Teste a API de WhatsApp da D-API3 dias grátis, sem cartão.[Começar trial grátis](https://app.d-api.cloud/register)

## Continue lendo

-   [Guia da API de WhatsAppBotões e listas no WhatsApp](https://d-api.cloud/api-whatsapp-botoes-e-listas)
-   [Guia da API de WhatsAppAPI de grupos do WhatsApp](https://d-api.cloud/api-whatsapp-grupos)
-   [Guia da API de WhatsAppChatbot de WhatsApp com IA](https://d-api.cloud/api-whatsapp-chatbot-com-ia)
-   [Guia da API de WhatsAppSelf-hosted vs gerenciada](https://d-api.cloud/api-whatsapp-self-hosted-vs-gerenciada)

## Teste a API de WhatsApp da D-API

Trial de 3 dias com acesso completo. Sem cartão, sem fidelidade.

[Começar trial grátis](https://app.d-api.cloud/register)[Ver documentação](https://docs.d-api.cloud/)