API reference

whatsapp.media

Upload media assets to Meta, fetch media metadata with temporary CDN URLs, download raw binary data, and delete media files.

upload

whatsapp.media.upload(file: Blob | Buffer, options: { type: string; filename?: string }, opts?: { phoneNumberId?: string }): Promise<WhatsappResponse<{ id: string }>>

Uploads a binary file or Node.js buffer to Meta's media store and returns a mediaId ready for sending in messages:

upload-media.ts

import { readFile } from "node:fs/promises";

// Read local file into a Buffer
const imageBuffer = await readFile("./receipt.png");

const { data: media, error } = await whatsapp.media.upload(imageBuffer, {
  type: "image/png",
  filename: "receipt.png",
});

if (error) {
  console.error("Upload failed:", error.message);
} else {
  console.log("Uploaded Media ID:", media.id);

  // Send the uploaded media in a message
  await whatsapp.messages.sendImage("15551234567", {
    mediaId: media.id,
    caption: "Here is your receipt",
  });
}

Media IDs uploaded via the API are valid for 30 days and are scoped to the sender Phone Number ID.

get (Inspect Metadata)

whatsapp.media.get(mediaId: string): Promise<WhatsappResponse<MediaMetadata>>

Retrieves metadata and a short-lived temporary download URL for any media ID (including inbound media sent by customers):

const { data: meta, error } = await whatsapp.media.get("media_id_12345");

if (meta) {
  console.log("Download URL:", meta.url);
  console.log("MIME Type:", meta.mime_type);
  console.log("File Size (bytes):", meta.file_size);
  console.log("SHA256 Hash:", meta.sha256);
}

download (Fetch Raw Binary)

whatsapp.media.download(mediaId: string): Promise<WhatsappResponse<ArrayBuffer>>

Automatically resolves the temporary download URL and downloads the binary payload using the client's authentication headers:

download-inbound.ts

import { writeFile } from "node:fs/promises";

// Download inbound photo from customer
const { data: arrayBuffer, error } = await whatsapp.media.download("media_id_12345");

if (error) {
  console.error("Download failed:", error.message);
} else {
  // Convert ArrayBuffer to Buffer and save to disk
  await writeFile("./customer-upload.jpg", Buffer.from(arrayBuffer));
  console.log("File saved successfully!");
}

delete

whatsapp.media.delete(mediaId: string): Promise<WhatsappResponse<{ success: boolean }>>

const { data, error } = await whatsapp.media.delete("media_id_12345");
console.log("Deleted:", data?.success);

Supported Media Formats & Limits

Parameter	Type	Description
Images	image/jpeg, image/png	Up to 5 MB. Formats: .jpg, .jpeg, .png
Documents	application/pdf, application/msword, text/plain, etc.	Up to 100 MB. Any valid document MIME type.
Audio	audio/aac, audio/mp4, audio/mpeg, audio/amr, audio/ogg	Up to 16 MB. Voice notes use audio/ogg with opus codec.
Video	video/mp4, video/3gpp	Up to 16 MB. H.264 video codec and AAC audio codec recommended.
Stickers	image/webp	Up to 100 KB (static) or 500 KB (animated). Dimensions: exactly 512x512 pixels.