Received media (download)

When a contact sends a photo, audio, video, document or sticker, Meta delivers only the media id in the webhook — not the file:

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

Downloading straight from Meta requires the Meta token (which Stevo never exposes) and the URL expires within minutes. That is why there are three ways to get the file — all using the Official API token of your instance (the apikey shown on the instance screen).

1. Via webhook — already resolved

If the instance has a Webhook (Official API) configured, every message with media arrives with an extra stevo.media block — the original Meta payload stays untouched:

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

url is a public, permanent link (Stevo storage). If Stevo cannot download from Meta, the webhook is still delivered, with stevo.media.error instead of url.

2. Via gateway — GET /v1/media/{mediaId}

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

Response: the binary with the correct Content-Type, Content-Length, Content-Disposition (suggested name {id}.{ext}) and X-Media-Sha256.

Metadata only, without downloading:

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

Full reference: Official API (Scalar).

3. Via 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 ?? 'file.bin', media.data);

const info = await meta.getMediaInfo('1436196501752591'); // metadata only

See Official SDK — stevo-sdk.

Tips

• Voice notes arrive as audio/ogg; codecs=opus (16 kHz, mono).
• Meta keeps media for a limited time (~30 days): download as soon as you receive the webhook and store it on your side — or use stevo.media.url, which does not expire.
• Missing/expired media on Meta → 404 with error: meta_error.
• Downloads count towards the gateway management rate limit (X-RateLimit-* headers).