Pular para o conteúdo principal

Medios recibidos (descarga)

Cuando un contacto envía foto, audio, vídeo, documento o sticker, Meta entrega en el webhook solo el id del medio — no el archivo:

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

Descargar directo de Meta exige el token de Meta (que Stevo nunca expone) y la URL caduca en minutos. Por eso hay tres formas de obtener el archivo — todas con el token de la API Oficial de tu instancia (la apikey que aparece en la pantalla de la instancia).

1. Por webhook — ya llega resuelto​

Si la instancia tiene Webhook (API Oficial) configurado, cada mensaje con medios llega con un bloque extra stevo.media — el payload original de Meta sigue intacto:

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

url es un enlace público y permanente (almacenamiento de Stevo). Si Stevo no logra descargar de Meta, el webhook llega igual, con stevo.media.error en lugar de url.

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

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

Respuesta: el binario con Content-Type correcto, Content-Length, Content-Disposition (nombre sugerido {id}.{ext}) y X-Media-Sha256.

Solo los metadatos, sin descargar:

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/..." }

Referencia completa: API Oficial (Scalar).

3. Por el SDK​

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

const info = await meta.getMediaInfo('1436196501752591'); // solo metadatos

Ver SDK oficial — stevo-sdk.

Consejos​

  • Los audios de voz llegan como audio/ogg; codecs=opus (16 kHz, mono).
  • Meta guarda el medio por tiempo limitado (~30 días): descarga apenas recibas el webhook y guárdalo de tu lado — o usa stevo.media.url, que no caduca.
  • Medio inexistente/caducado en Meta → 404 con error: meta_error.
  • La descarga cuenta en el rate limit de gestión del gateway (headers X-RateLimit-*).