Download inbound media

GET /v1/media/:mediaId

Building with AI? Connect it to your account over MCP: it checks your setup, creates webhooks and templates with your confirmation and writes the code for you. See how →

A message.received event carries a media id, not the bytes. Downloading them needs the connection's token, which we hold → fetch them at GET /v1/media/:mediaId. We stream it straight through (never stored). A media id that is not yours → 404 (we never confirm someone else's media).

# The media id comes from a message.received event: data.message.image.id (etc.)
curl https://api.waiaconnect.com/v1/media/1234567890 \
  -H "Authorization: Bearer wc_live_YOUR_API_KEY" \
  -o downloaded-media.bin   # Content-Type comes back on the response

import { writeFile } from "fs/promises";
// The media id comes from a message.received event: data.message.image.id (etc.)
const res = await fetch("https://api.waiaconnect.com/v1/media/1234567890", {
  headers: { "Authorization": "Bearer wc_live_YOUR_API_KEY" }
});
if (res.status === 404) throw new Error("Not your media id");
const buf = Buffer.from(await res.arrayBuffer());
await writeFile("downloaded-media.bin", buf); // res.headers.get("content-type") = the MIME

<?php
// The media id comes from a message.received event: data["message"]["image"]["id"] (etc.)
$ch = curl_init("https://api.waiaconnect.com/v1/media/1234567890");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer wc_live_YOUR_API_KEY"],
]);
$bytes = curl_exec($ch);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) === 404) { throw new Exception("Not your media id"); }
file_put_contents("downloaded-media.bin", $bytes);

import requests
# The media id comes from a message.received event: data["message"]["image"]["id"] (etc.)
res = requests.get("https://api.waiaconnect.com/v1/media/1234567890",
  headers={"Authorization": "Bearer wc_live_YOUR_API_KEY"}, stream=True)
if res.status_code == 404:
    raise Exception("Not your media id")
with open("downloaded-media.bin", "wb") as f:
    for chunk in res.iter_content(8192):
        f.write(chunk)  # res.headers["content-type"] = the MIME

The mediaId comes from the event: data.message.image.id (or .document.id, .audio.id, .video.id).

⚠ An identifier that arrives by webhook expires at Meta after a few days (Meta sets the term): after that Meta no longer resolves it and we return 404. If you need the file for longer, download and store it yourself.

This is also the only kind of identifier that exists in Connect — there is no upload. To SEND a file of your own, see "Send media".