Guides

Session Media

Send images, documents, video, and audio with POST /messages inside an open customer session — as multipart file uploads.

Templates vs session media Outside the Cloud 24h window, use an approved template with a DOCUMENT/IMAGE/VIDEO header instead — see Template Media Headers.

1. Supported fields

Upload field (multipart)	Notes
`image`	JPG/PNG/WebP and common formats
`document`	PDF and office docs
`video`	MP4 preferred
`audio`	Common audio types. Device voice notes: `ptt=1` + OGG/Opus

message is optional when sending media and becomes the caption when provided.

No URL fields POST /v1/messages does not support image_url, document_url, video_url or audio_url. A request with only a URL field fails with validation_error. Upload the file as multipart instead. To send a file by URL, use an approved template with a DOCUMENT/IMAGE/VIDEO header and header_media_url.

2. Scenario — multipart upload

curl -X POST "https://staging-mobile.washeej.com/v1/messages" \
  -H "client-id: YOUR_CLIENT_ID" \
  -H "client-secret: YOUR_CLIENT_SECRET" \
  -F "mobile_code=966" \
  -F "mobile=500000000" \
  -F "whatsapp_account_id=YOUR_ACCOUNT_ID" \
  -F "message=Your invoice is attached" \
  -F "document=@/path/to/INV-1001.pdf;type=application/pdf"

3. Practical limits

API accepts large uploads; WhatsApp / Meta still enforce channel-side limits (prefer PDF ≤ 100 MB, images ≤ 5 MB, video ≤ 16 MB on Cloud).
Give the uploaded document a clear file name so the customer sees it.
Works on Cloud and Device channels; Cloud still requires an open session outside templates.

4. Device voice notes vs audio files

ptt=1 (or voice=1) on a Device channel sends a WhatsApp voice note.
Recommended file: OGG container, Opus codec, audio/ogg (typical extension .ogg / .oga).
webm/opus without ptt is delivered as a file attachment, not a voice bubble.
Inbound device voice notes are stored as audio (GOWA ptt is normalized).
Download inbound/outbound media with GET /v1/messages/{id}/media — do not request /statics/media/… on app.washeej.com.