Links de mídia da conversa
Abre uma imagem, áudio, vídeo ou documento da conversa de WhatsApp por um link assinado, sem login.
Quando a loja exporta conversas do atendimento (por exemplo, uma planilha CSV), as mensagens com mídia levam um link assinado em vez do arquivo. Quem recebe a planilha abre o link direto no navegador, sem login. A assinatura do próprio link é a autorização.
Há dois formatos de link, e os dois devolvem o arquivo da mensagem.
Abrir pelo link da conversa
/api/v1/storefront/wa-coex/inbox-media/{token}PúblicaDevolve a mídia de uma mensagem da conversa, por um link assinado
O token carrega a loja e a mensagem, e pode ter prazo de validade. Um token adulterado, de outra loja ou vencido responde 404.
Parâmetros de caminho
tokenstringobrigatórioErros
| Status | Quando | Corpo |
|---|---|---|
| 404 | Token inválido, vencido, com assinatura errada ou de uma loja que não existe. | Texto simples not found |
| 404 | A mensagem não tem mídia disponível. | {"error":"media not found"} |
| 502 | Não foi possível baixar a mídia agora, ou ela veio vazia. | {"error":"<texto>"} ou {"error":"empty media"} |
Abrir pelo link compartilhável
/api/v1/storefront/wa-coex/media-share/{token}PúblicaDevolve a mídia de uma mensagem por um link de compartilhamento assinado
Faz o mesmo que o link acima, com um token de outro formato. Aqui a loja é resolvida pelo endereço (host) da requisição, e o token precisa ser da mesma loja: um token da loja A usado no endereço da loja B é recusado.
Se a mídia já é um endereço público (http ou https), a resposta é um redirecionamento 302 para ele. Caso contrário, a plataforma busca o arquivo, guarda uma cópia e o devolve com o tipo registrado na mensagem (Content-Disposition: inline, Cache-Control: private, max-age=3600).
Parâmetros de caminho
tokenstringobrigatórioErros
| Status | Quando | Corpo |
|---|---|---|
| 302 | A mídia é um endereço público: segue para ele. | Sem corpo |
| 400 | A mensagem não tem mídia, ou o endereço da mídia não é de um tipo aceito. | {"error":"message has no media"}, {"error":"unsupported media url scheme"} ou {"error":"missing media id"} |
| 403 | Token inválido, vencido ou com assinatura errada. | {"error":"invalid or expired media link"} |
| 403 | O token é de outra loja, ou a requisição não resolve uma loja. | {"error":"tenant mismatch"} ou {"error":"tenant context required"} |
| 404 | A mensagem não existe. | {"error":"message not found"} |
| 500 | Falha ao consultar a mensagem. | {"error":"media lookup failed"} |
| 502 | Não foi possível baixar a mídia agora. | {"error":"media fetch failed: <detalhe>"} |
| 503 | A loja não tem o acesso à API do WhatsApp configurado. | {"error":"whatsapp api token not configured"} |
O que a resposta traz
As duas rotas devolvem o arquivo no corpo, não JSON.
No link da conversa (inbox-media), a mídia vem do cliente da loja e por isso é tratada como não confiável:
- Só tipos seguros são exibidos no navegador (
Content-Disposition: inline): imagens JPEG, PNG, WebP e GIF; áudio OGG, MP3, MP4, AAC, AMR e WebM; vídeo MP4, 3GPP e WebM; e PDF. Qualquer outro tipo, SVG inclusive, é devolvido comoapplication/octet-streampara download (attachment). - Toda resposta leva
X-Content-Type-Options: nosniff,Content-Security-Policy: default-src 'none'; sandboxeCache-Control: private, no-store. - O arquivo é lido até 16 MB.
Exemplo de requisição
curl -o midia.bin "$BASE_URL/api/v1/storefront/wa-coex/media-share/$SIGNED_TOKEN"