01 · Definition
What is the WhatsApp media file limit?
Media file limits are the formats and maximum file sizes the WhatsApp Cloud API accepts for each kind of Media Message. Every file you send, whether stored first through Media Upload or referenced by link, must match a supported MIME type for its media type and stay under that type's cap, or the request fails before anything reaches the customer.
The table is short. Images: JPEG (image/jpeg) or PNG (image/png), 8-bit RGB or RGBA, up to 5 MB. Video: MP4 (video/mp4) or 3GPP (video/3gpp) with the H.264 video codec and AAC audio, one audio stream or none, up to 16 MB. Audio: AAC, AMR, MP3 (audio/mpeg), M4A (audio/mp4) or OGG (audio/ogg) with the Opus codec and mono input, up to 16 MB; a Voice Note must be OGG with Opus. Documents: plain text, PDF, DOC and DOCX, XLS and XLSX, PPT and PPTX, up to 100 MB. Stickers: WebP only, 100 KB static or 500 KB animated.
The limits apply in both directions, with one twist: the largest file a customer can send you is 100 MB, and a bigger one never arrives as media; your webhook gets error 131052 instead. Limits are per file, and they are separate from lifetimes: an uploaded Media ID lasts 30 days, an ID received in a webhook can be downloaded for 7 days, and a download URL works for 5 minutes. The Image Message, Document Message and Sticker Message pages cover how each type behaves; this page is the reference table behind them.
Key takeaways
- Each media type has its own cap: images 5 MB, video and audio 16 MB, documents 100 MB, stickers 100 KB static or 500 KB animated.
- Images are JPEG or PNG; video is MP4 or 3GPP with H.264 and AAC; audio is AAC, AMR, MP3, M4A or OGG with Opus, mono.
- WebP is for stickers only; documents cover PDF, Word, Excel, PowerPoint and plain text.
- Customers can send you files of up to 100 MB; a larger file reaches you only as webhook error 131052.
- Detect the real MIME type and size before uploading, and convert or compress rather than retrying.
02 · Specifications
The WhatsApp media file limit: key facts and limits
| Image | JPEG, PNG · 8-bit RGB/RGBA · 5 MB |
|---|---|
| Video | MP4, 3GPP · H.264 + AAC · 16 MB |
| Audio | AAC, AMR, MP3, M4A, OGG (Opus, mono) · 16 MB |
| Document | TXT, PDF, DOC(X), XLS(X), PPT(X) · 100 MB |
| Sticker | WebP · 100 KB static, 500 KB animated |
| Largest inbound file | 100 MB; larger arrives as error 131052 |
| Media ID lifetime | 30 days uploaded · 7 days from webhooks |
| Download URL | Expires after 5 minutes |
03 · Operation
How does the WhatsApp media file limit work?
Detect the real type
Read the file's bytes with
file --mime-typeor a file-type library, and the codecs withffprobe. Extensions and the MIME type a browser reports are often wrong.Compare it with the table
Look up the cap for that MIME type and media kind. Reject unsupported types early (HEIC, WebP as an image, MOV, WAV, HEVC video) with a clear reason.
Convert or compress
Images: resize and save as JPEG at around 80% quality. Video: re-encode to H.264 with AAC at a lower resolution or bitrate. Voice: OGG with Opus, mono. Stickers: WebP within 100 KB or 500 KB.
Upload with the right type
POST to
/{PHONE_NUMBER_ID}/mediawithtypeset to the detected MIME type, then send the returned media ID. A file that passed your check should not fail on size.Handle oversized inbound files
When a webhook reports error 131052 for a file over 100 MB, ask the customer to send a smaller file or a link instead of waiting for media that will never arrive.
04 · Code samples
The WhatsApp media file limit in code
# 1. What is this file really? (check bytes and codecs, not the extension)file --mime-type -b upload.mov # video/quicktime: not accepted, convert itffprobe -v error -show_entries stream=codec_name,codec_type -of csv=p=0 upload.mov# 2. Video: H.264 + AAC in MP4, one audio stream, 720p, sized well under 16 MBffmpeg -i upload.mov -map 0:v:0 -map 0:a:0? -c:v libx264 -preset slow -crf 28 \-vf "scale=-2:720" -c:a aac -b:a 96k -movflags +faststart clip.mp4# 3. Voice note: OGG with the Opus codec, monoffmpeg -i memo.m4a -c:a libopus -b:a 32k -ac 1 voice.ogg# 4. Photo (HEIC or a huge PNG): JPEG, long edge 1600 pxmagick IMG_4021.HEIC -resize "1600x1600>" -quality 82 photo.jpg# 5. Check the results against the capsls -l clip.mp4 voice.ogg photo.jpg
`-map 0:a:0?` keeps at most one audio stream, which is all WhatsApp video allows.
05Playground
A working model of Media File Limits. Use its controls to replay it step by step.
How big can each file be?
- Maximum file size
Bars · MB
Highest: Document at 100 MB. Lowest: Static sticker at 0.1 MB.
Hover, focus or tap a column for exact values; press it to pin.
| Category | Maximum file size |
|---|---|
| Image | 5 |
| Video | 16 |
| Audio | 16 |
| Document | 100 |
| Static sticker | 0.1 |
| Animated sticker | 0.5 |
06 · Cautions
Common mistakes with the WhatsApp media file limit
Trusting the file extension
A
.mp4can hold HEVC video and a.jpgcan really be WebP or HEIC. Detect the MIME type from the bytes and inspect codecs before deciding a file is fine.HEVC video or extra audio tracks
Many phones record HEVC by default, and screen recordings can carry two audio streams. WhatsApp video needs H.264 and at most one AAC stream, so re-encode.
Stereo or non-Opus OGG for voice
OGG audio is accepted only with the Opus codec and mono input, and a voice note must be OGG with Opus. Convert MP3 or M4A recordings before sending them as voice.
Squeezing until it passes
A 95 MB scanned PDF is within the limit but slow on mobile data, and a 3-minute video crushed into 16 MB looks poor. Split documents, shorten clips or send a link instead.
Retrying a size or format error
Retries never fix an oversized or unsupported file. Route the failure to conversion, or send the content as a link, and alert on repeated media errors.
07 · Worked example: Swatch videos for a Coimbatore textile exporter
Example: Swatch videos for a Coimbatore textile exporter
A Coimbatore textile exporter's sales team shares fabric swatch videos shot on phones: 45 seconds of 4K HEVC, well over 100 MB each (illustrative). The upload worker runs ffprobe, sees HEVC and a size far above 16 MB, and re-encodes to 720p H.264 with AAC at a modest bitrate, landing near 9 MB. Swatch stills go as 1,600-pixel JPEGs under 1 MB, and the price list stays a 2 MB PDF document. When a buyer sends back a 140 MB inspection video, the webhook reports error 131052, and the bot automatically asks for a shorter clip or a shared-drive link.
08 · Rationale
Why does the WhatsApp media file limit matter?
Most failed media sends are not network problems. They are a 7 MB PNG, a 40 MB phone video, an iPhone HEIC photo, an HEVC clip or a stereo OGG file. Checking type and size before upload turns a confusing failed status into a fix you can automate, and the limits shape product decisions too: a 30-second clip instead of a three-minute one, a PDF catalogue instead of twenty photos, a link instead of a 200 MB walkthrough.
09 · Recommended practice
Best practices for the WhatsApp media file limit
- Treat each cap as a ceiling, not a target: lighter files arrive faster on mobile data.
- Build conversion into the upload worker (ffmpeg, ImageMagick or sharp) instead of asking teams to resize by hand.
- Send long videos as a link behind an Interactive CTA URL Message rather than crushing them under 16 MB.
- Log the detected MIME type, codec and size with every failed media send so patterns show up quickly.
10 · Questions and answers
Media File Limits FAQs
- What is the maximum video size on the WhatsApp Business API?
- 16 MB, for MP4 or 3GPP files that use H.264 video and AAC audio with a single audio stream or none. Re-encode HEVC or multi-track recordings and lower the resolution or bitrate to fit.
- What is the document size limit on the WhatsApp Cloud API?
- 100 MB, for plain text, PDF, Word, Excel and PowerPoint files (old and new Office formats). It is the largest cap of any media type and the most a customer can send you, too.
- Which audio format should I use for a WhatsApp voice note?
- OGG with the Opus codec, mono, sent with
voice: true. Meta notes the play icon appears only for files of 512 KB or less; larger ones show a download icon instead. - Why does WhatsApp reject my sticker?
- Stickers must be WebP and no larger than 100 KB static or 500 KB animated. PNG or JPEG files are not accepted as stickers, and WebP is not accepted as an ordinary image.
- Do the same limits apply to files customers send me?
- The ceiling for inbound media is 100 MB. When a customer sends something larger, your webhook receives error 131052 instead of the file, so ask them for a smaller file or a link.