The WhatsApp Media Library stores uploaded media files that can be reused in templates, broadcasts, auto replies, transactional notifications, and live chat messages.
Media files uploaded to WhatsApp Cloud API receive a Media ID from Meta. This Media ID is used when sending media messages or media-header templates.
✅ Before You Begin #
Make sure you have:
- ✅ Permission to view Madias.
- ✅ Add permission if you need to upload or restore media.
- ✅ Delete permission if you need to remove media.
- ✅ A valid WhatsApp Business Cloud API connection.
- ✅ A supported file type and size for the selected media type.
📍 Where to Find It #
Go to:
Integrations → WhatsApp Media List
The page displays all uploaded media files as cards.
📋 Media List Overview #
Each media card shows:
- 🆔 Media ID
- 🗂️ File Name
- 🧩 Media Type
- 📅 Date Created
- ⏳ Expiry status
- 👁️ View button
- ⬇️ Download button
- 🔁 Restore/Re-upload button, when media is expired or near expiry
- 🗑️ Delete button
At the top of the page, you can see the total number of media records.
⏳ Media Expiry #
Meta automatically deletes uploaded WhatsApp media after 14 days from the creation date.
The Media List shows whether each file is:
- ✅ Still active
- ⚠️ Near expiry
- ❌ Expired
If the media is still active, the card shows how many days remain before expiry.
When the media is expired or close to expiry, a restore/re-upload button appears.
🔎 Search Media #
Use the search box to search by:
- Media ID
- File name
Steps:
- Enter the Media ID or file name.
- Click the search icon.
- Matching media records are displayed.
If you clear the search field, the list reloads.
🧩 Filter by Media Type #
Use the filter dropdown to filter media by type.
Available media types:
- Audio
- Document
- Image
- Sticker
- Video
Use Clear Filter to return to all media.
➕ Upload New Media #
Click Upload Media.
The upload page includes:
- Media Type
- Media File
- Upload Type
🧾 Upload Fields #
🧩 Media Type #
Choose the type of file you want to upload.
Supported media types:
- Audio
- Document
- Image
- Sticker
- Video
The selected media type controls which file extensions are allowed.
📎 Media File #
Choose the file from your device.
The file must match the selected media type. If the file extension or size is not valid, the system shows an error and clears the selection.
⬆️ Upload Type #
Choose the upload method:
- Normal Upload
- Resumable Upload
Use Normal Upload for standard media uploads that should return a WhatsApp Media ID.
Use Resumable Upload when preparing uploads that need resumable file handling, such as media used during template creation workflows.
📏 Supported File Types and Size Limits #
🎧 Audio #
Supported extensions:
.aac.amr.mp3.m4a.ogg
Maximum size:
- 16 MB
📄 Document #
Supported extensions:
.txt.xls.xlsx.doc.docx.ppt.pptx.pdf
Maximum size:
- 100 MB
🖼️ Image #
Supported extensions:
.jpeg.jpg.png
Maximum size:
- 5 MB
🙂 Sticker #
Supported extension:
.webp
Maximum size:
- 0.5 MB
🎥 Video #
Supported extensions:
.3gp.mp4
Maximum size:
- 16 MB
🆔 Media ID #
After a successful normal upload, Meta returns a Media ID.
This Media ID can be used in:
- Broadcast campaigns
- Template messages
- Auto replies
- Transactional notifications
- Chatbot media nodes
- Live chat media messages
Keep in mind that the Media ID expires after Meta’s media retention period, so you may need to restore it later.
🔁 Restore or Re-upload Expired Media #
If the media is expired or near expiry, click the restore icon.
The system will:
- Use the existing uploaded file saved on the server.
- Upload it again to Meta.
- Receive a new Media ID.
- Update the media record with the new Media ID.
After restoring, the page refreshes and shows the new Media ID.
👁️ View Media #
Click the eye icon to open the uploaded file in a new browser tab.
For images, you can preview the actual image.
For documents, audio, stickers, or videos, the browser opens the stored file if supported.
⬇️ Download Media #
Click the download icon to download the stored media file.
This downloads the original saved file from the application media uploads folder.
🗑️ Delete Media #
Click the delete icon.
A confirmation message appears:
Are you sure you want to delete this Media? Please note that any Auto Replies or Transactional Notifications associated with this media will be deactivated.
Click Delete to confirm.
Important:
- Deleting media removes the media record.
- The system also attempts to delete the media from the WhatsApp Cloud API.
- Linked auto replies or transactional notifications may be deactivated if they depend on the deleted media.
🔗 Where Media Is Used #
Uploaded media can be selected in several areas of the platform:
- WhatsApp template media headers
- Broadcast campaigns
- Auto replies
- Transactional templates
- Chatbot media messages
- Live chat media sending
For template headers, the media type should match the template header type.
Example:
- IMAGE template header → Image media
- VIDEO template header → Video media
- DOCUMENT template header → Document media
⚠️ Common Issues #
Upload fails #
Check that:
- Media type is selected.
- A file is selected.
- File extension matches the selected media type.
- File size is within the allowed limit.
- WhatsApp phone connection is active.
The media is expired #
Meta deletes media after 14 days. Use the restore button to re-upload and generate a new Media ID.
Media does not appear in template selection #
Check that:
- The media type matches the template header type.
- The media was uploaded successfully.
- The media is not deleted.
Restore fails #
Check that:
- The original file still exists on the server.
- The WhatsApp connection is valid.
- The file type is still supported.
✅ Best Practices #
- Use clear file names before uploading.
- Upload only production-ready files.
- Restore media before running important broadcasts.
- Avoid deleting media used by active auto replies or transactionals.
- Use Link URL instead of Media ID when you want to avoid media expiry.
- Review near-expiry media regularly.
- Keep images optimized under 5 MB.
🧠 Summary #
The WhatsApp Media Library stores uploaded media and Meta Media IDs for use across messaging features. Because Meta media expires after 14 days, the Media List helps you monitor expiry, restore files, download files, filter by type, and safely manage media used in automations.
