Pular para o conteúdo principal

Mídia recebida (download)

Quando um contato manda foto, áudio, vídeo, documento ou sticker, a Meta entrega no webhook apenas o id da mídia — não o arquivo:

{ "type": "audio", "audio": { "id": "1436196501752591", "mime_type": "audio/ogg; codecs=opus", "sha256": "..." } }

Baixar direto da Meta exige o token da Meta (que a Stevo nunca expõe) e a URL expira em minutos. Por isso existem três jeitos de pegar o arquivo — todos com o token da API Oficial da sua instância (a apikey que aparece na tela da instância).

1. Pelo webhook — já vem resolvido​

Se a instância tem Webhook (API Oficial) configurado, toda mensagem com mídia chega com um bloco extra stevo.media — o payload original da Meta continua intacto:

{
  "object": "whatsapp_business_account",
  "entry": [ ... ],
  "stevo": {
    "instance": "minha-instancia",
    "media": {
      "id": "1436196501752591",
      "type": "audio",
      "mime_type": "audio/ogg",
      "file_size": 344266,
      "url": "https://hel1.your-objectstorage.com/stevo/api-oficial/minha-instancia/1787...-1436196501752591.ogg",
      "download_path": "/v1/media/1436196501752591"
    }
  }
}

url é um link público e permanente (armazenamento da Stevo). Se a Stevo não conseguir baixar da Meta, o webhook vem normal, com stevo.media.error no lugar de url.

2. Pelo gateway — GET /v1/media/{mediaId}​

curl https://apimeta.shurima.cloud/v1/media/1436196501752591 \
  -H "Authorization: Bearer SEU_TOKEN" \
  -o audio.ogg

Resposta: o binário com Content-Type correto, Content-Length, Content-Disposition (nome sugerido {id}.{ext}) e X-Media-Sha256.

Só os metadados, sem baixar:

curl "https://apimeta.shurima.cloud/v1/media/1436196501752591?metadata=1" \
  -H "Authorization: Bearer SEU_TOKEN"
# { "id": "...", "mime_type": "audio/ogg", "sha256": "...", "file_size": 344266, "download_path": "/v1/media/..." }

Referência completa: API Oficial (Scalar).

3. Pelo SDK​

const meta = await stevo.oficial(instanceId);
const midia = await meta.downloadMedia('1436196501752591');
// midia = { data: Uint8Array, mimeType, fileSize, sha256, fileName }
await fs.promises.writeFile(midia.fileName ?? 'arquivo.bin', midia.data);

const info = await meta.getMediaInfo('1436196501752591'); // só metadados

Veja SDK oficial — stevo-sdk.

Dicas​

  • Áudios de voz chegam como audio/ogg; codecs=opus (16 kHz, mono).
  • A Meta guarda a mídia por tempo limitado (~30 dias): baixe assim que receber o webhook e guarde do seu lado — ou use o stevo.media.url, que não expira.
  • Mídia inexistente/expirada na Meta → 404 com error: meta_error.
  • O download conta no rate limit de gestão do gateway (headers X-RateLimit-*).