Media (image, audio, video, document)

Media messages

Images, audio, video, documents and stickers all send the same way: upload the file once to get a mediaId, then send that mediaId. Splitting the upload from the send lets you reuse one uploaded file across many recipients and keeps the send body tiny.

Step 1 — upload the file

Post the raw file as multipart form-data (field name file) to the channel's media route. Telenow uploads it to WhatsApp and hands back a mediaId plus what it detected about the file.

curl -X POST https://api.telenow.ai/api/app-whatsapp/channels/b1e2c3d4-…/media \
  -H "Authorization: Bearer vai_app_…" \
  -F "[email protected]"

{
  "success": true,
  "data": {
    "mediaId": "1029384756574839",
    "mime": "application/pdf",
    "filename": "invoice-1234.pdf",
    "bytes": 84213
  }
}

The message type is inferred from the file's MIME — you never pass a type. A application/pdf becomes a document, an image/jpeg becomes an image, and so on. If the file exceeds its cap you get a 413 before anything is sent (see caps).

Step 2 — send the mediaId

Post to /send with the mediaId from step 1. Add a caption for image, video or document; omit it for audio and stickers.

curl -X POST https://api.telenow.ai/api/app-whatsapp/send \
  -H "Authorization: Bearer vai_app_…" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "b1e2c3d4-…",
    "to": "+919876543210",
    "mediaId": "1029384756574839",
    "caption": "Your invoice for order #1234"
  }'

{ "success": true, "data": { "wamid": "wamid.HBgLMTQxNTU1MDEwMBUCABIYFj…" } }

Media is free-form content, so it only sends inside the 24-hour customer service window; outside it, start with a template. As with every send, dedupe on the returned wamid and track delivery via whatsapp.message.status.

Media types

Each type has its own size cap and its own rule about captions. A caption is a text string that rides along with the file; WhatsApp only supports it on visual/attachment types.

Image

JPEG or PNG, up to 5 MB. Caption allowed. The caption renders under the image and is the natural place for a short line about what the customer is looking at.

Video

MP4, up to 16 MB. Caption allowed. Same placement as an image caption.

Document

Any file (PDF, spreadsheet, etc.), up to 100 MB. Caption allowed — it shows as the message text above the file card. The original filename from your upload is what the customer sees and downloads.

Audio

Up to 16 MB. No caption — WhatsApp renders audio as a standalone playable clip with no accompanying text, so any caption you send is dropped.

Sticker

WebP, up to 500 KB. No caption. Stickers are square, transparent-background images and, like audio, carry no text.

Size caps & captions

TypeMax sizeCaption?
Image5 MBYes
Video16 MBYes
Document100 MBYes
Audio16 MBNo
Sticker500 KBNo

Exceeding a cap fails the upload with 413 — the file never reaches the send step. A caption on audio or sticker is silently ignored rather than rejected.

Quote a message

Add reply_to (the wamid of the message you're answering) to the send body to thread your media under it — the same field documented in Reply to a specific message. It works alongside mediaId, location, interactive, and every other content type:

{ "channelId": "b1e2c3d4-…", "to": "+919876543210",
  "mediaId": "1234567890",
  "caption": "Here's your receipt.",
  "reply_to": "wamid.HBgLMTQx…" }

Receiving media

When a customer sends you a photo, voice note, or file, it arrives on the whatsapp.message.received webhook. The message's content.media describes the attachment (id, mime, filename), and the top-level media object gains a signedUrl once Telenow has fetched the bytes.

{
  "event": "whatsapp.message.received",
  "channelId": "b1e2c3d4-…",
  "from": "+919876543210",
  "wamid": "wamid.HBgLM…",
  "type": "image",
  "content": {
    "media": { "id": "1122334455", "mime": "image/jpeg", "filename": "photo.jpg" }
  },
  "media": {
    "mime": "image/jpeg",
    "filename": "photo.jpg",
    "signedUrl": "https://…"
  },
  "timestamp": "2026-07-18T09:31:00Z"
}

The {id} in GET /media/{id} is the Telenow message-row id (a UUID) — obtain it from GET /api/app-whatsapp/threads/{id}/messages (the id field, or ready-made in media.url). It is not the wamid, and not content.media.id. Note the whatsapp.message.received webhook payload doesn't include this UUID, so for the webhook flow download inbound media via media.signedUrl instead.

curl -L https://api.telenow.ai/api/app-whatsapp/media/e5b2c9a4-1f7d-4c8a-9b2e-0a1b2c3d4e5f \
  -H "Authorization: Bearer vai_app_…" \
  -o inbound-photo.jpg

The response streams the raw bytes as an attachment (Content-Disposition: attachment, X-Content-Type-Options: nosniff). See Webhooks & events for the full received payload and signature verification.