Baixar mídia
Baixa um arquivo de mídia recebido (imagem, vídeo, áudio, documento ou figurinha) pela URL assinada que o webhook message.incoming traz em data.media.url. Não leva chave de API: a própria URL é a credencial, válida até data.media.expiresAt. Use a URL exatamente como recebida; sem assinatura, expirada ou alterada, ela responde 404, igual a um arquivo que não existe. Sem chave de API: a URL assinada é a credencial.
Parâmetros de caminho
connectionIdstring · uuidobrigatórioIdentificador da conexão (o número) que recebeu a mídia, como vem na URL assinada.
fileNamestringobrigatórioNome com que a apiwpp guardou o arquivo: o id da mensagem mais a extensão (3EB0C767D26A8A0F2B41.jpg). É o mesmo valor de data.media.fileName, não o nome original do documento.
Parâmetros de consulta
expstringMomento de expiração da URL, em segundos unix. A partir dele, a URL responde 404. Na prática é obrigatório: sem ele, a resposta é 404.
sigstringA assinatura da URL: HMAC-SHA256 em base64url (43 caracteres) sobre connectionId/fileName/exp. Na prática é obrigatório: sem ele, ou com qualquer parte da URL alterada, a resposta é 404.
Respostas
| Código | Erro e descrição |
|---|---|
| 200 | O arquivo, com o Content-Type da extensão do nome (image/jpeg, video/mp4, audio/ogg, application/pdf…; application/octet-stream para as demais), Content-Length e Cache-Control que permite guardá-lo até a URL expirar (no máximo 1 hora). |
| 400 | FST_ERR_VALIDATIONOs parâmetros não seguem o formato da operação (por exemplo, connectionId que não é um UUID). A assinatura é conferida antes dessa validação, então uma URL sem assinatura válida responde 404, nunca 400; com a URL exatamente como a apiwpp entregou, este status não acontece. |
| 404 | A URL não tem assinatura, expirou, foi alterada em qualquer parte ou o arquivo não existe mais (apagado depois do prazo): todos esses casos respondem igual, com o corpo {"error": "Media not found"}. Não há como renovar a URL; a mídia só pode ser baixada enquanto o link do evento for válido. |
| 429 | Requisições demais deste IP de origem (por padrão, 600 por minuto): espere os segundos de Retry-After. Veja Limites.Cabeçalho: Retry-After |
Detalhes
Não monte a URL. Os parâmetros exp e sig são gerados pela apiwpp quando o evento é enviado: sig é um HMAC-SHA256 (em base64url) sobre connectionId/fileName/exp, com uma chave que só o gateway conhece. Faça GET na URL de data.media.url como ela veio, com o mesmo host. Nos exemplos ao lado, os parâmetros aparecem separados só para mostrar o formato.
Sem credencial. A rota é pública e não lê o cabeçalho Authorization nem X-Api-Key: com ou sem chave, a resposta é a mesma. Por isso, quem tiver a URL baixa o arquivo até ela expirar. Trate o link como um segredo: não o registre em log nem o repasse.
Validade. Por padrão, a URL vale 24 horas a partir do envio do evento, e o arquivo é apagado 24 horas depois de recebido, qualquer que seja a validade da URL. Baixe o arquivo quando o evento chegar em vez de guardar o link. Não há como pedir uma URL nova: depois de expirada, a mídia não pode mais ser baixada pela API.
A resposta. O corpo é o próprio arquivo, com Content-Type pela extensão do nome: image/jpeg, image/png, image/gif, image/webp, video/mp4, video/quicktime, audio/ogg, audio/mpeg, audio/mp4, application/pdf, application/msword ou o tipo do .docx; qualquer outra extensão (inclusive .bin) vem como application/octet-stream. Content-Length traz o tamanho, e Cache-Control: private, max-age=<segundos> deixa o navegador guardar o arquivo por até 1 hora, nunca além da expiração da URL.
Direto no navegador. A resposta traz Cross-Origin-Resource-Policy: cross-origin, então a URL pode ser usada num <img>, num <video> ou num frame de PDF de outro domínio enquanto for válida.
Guia: Webhooks e assinatura