When a WhatsApp user sends an image, video, voice note, document, or sticker to your number, Wazapin alerts your server via a webhook. Follow this guide to identify media messages, retrieve their download URLs, and download the media files to your server or cloud storage.

​
When this matters

Inbound media handling is essential for:
  • Saving customer-uploaded PDFs, receipts, or invoices.
  • Processing user-submitted photos or videos for customer support.
  • Archiving voice notes (audio messages) for transcription or QA.

​
Processing flow

Downloading user-submitted media involves three main steps:

​
1. Detect media webhook

Wazapin POSTs a lightweight message.new webhook with a msg_type set to image, video, audio, document, or sticker. Here is an example webhook payload for an inbound image:
Inbound image webhook body
{
  "message_id": "9f1fd66d-c37a-4b50-a8c2-b4dca523f9c8",
  "conversation_id": "0f89b0f9-74b4-44f9-b9b6-48f6d4de57aa",
  "contact_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "channel_id": "wzp_abc123",
  "direction": "inbound",
  "from_phone": "6281234567890",
  "msg_type": "image"
}

​
2. Fetch the media URL

Call GET /v1/messages/ using the message_id from the payload. The API response will contain the content block with a direct download link:
  • For images/videos/audio/documents: content.media_url
  • For stickers: content.sticker_url

​
3. Download the file

Stream the binary content from media_url (or sticker_url) to your local file system, AWS S3, Google Cloud Storage, or other storage provider.

​
Code example

Here is how to catch the webhook, get the message details, and download the file: 
# 1. Fetch message details to get the media_url
curl -X GET "https://api.wazapin.com/v1/messages/9f1fd66d-c37a-4b50-a8c2-b4dca523f9c8" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

# 2. Download the binary file directly using the media_url from the response
curl -o "receipt.png" "https://api.wazapin.com/v1/media/assets/download_url"

​
Channel support

Both official and unofficial channels support inbound media messages.
  • Official Channels: Handled via Meta’s secure media servers. Direct download URLs are proxy links provided by Wazapin and include expiring tokens.
  • Unofficial Channels: Pairs with WhatsApp Web to cache and upload media assets to Wazapin’s cloud store.
For details on supported media sizes and MIME types, see the Channel support matrix.

​
Troubleshooting

​
Expired media URLs

Wazapin media download URLs contain temporary access tokens. To prevent broken links, download the files immediately upon receiving the webhook. Do not store the media_url in your database expecting it to work indefinitely.

​
Wrong content-type or extensions

Wazapin proxy endpoints attempt to resolve correct MIME types and extensions. However, always validate the magic bytes or Content-Type headers when writing files to disk (e.g., verifying a .png file has png headers) to prevent execution vulnerabilities.

​
HTML landing page issues

If the downloaded file contains text resembling an HTML error page, check if the source URL has expired or if your API Key has permission to retrieve the message.

​
Next steps