How to retrieve files

How developers can retrieve any type of file (document, image, audio, video, etc.) from WhatsApp messages using Whapi.Cloud's API

If your system receives messages from users and you need to download the source files for internal processing, storage, or forwarding, you will find it useful to learn about two different ways to achieve this goal.

Whapi.Cloud provides programmatic access to media files received in WhatsApp chats or groups, regardless of whether the file is a PDF, image, audio recording, or video. You can either download the file directly via the API or set up automatic cloud storage using download links.

Method 1: Get the File by Media ID Using the Get Media Endpoint

When your webhook receives an incoming message that includes a file, you'll see a field such as document.id, image.id, or video.id. This is the Media ID — a unique identifier of the file stored temporarily on the WhatsApp server.

Webhook Example (Message with PDF document)

{
  "messages": [
    {
      "id": "tGZmYoiXecvbKahzwpwKmg-gEcTwl0rVw",
      "from_me": false,
      "type": "document",
      "chat_id": "919984351847@s.whatsapp.net",
      "timestamp": 1713201784,
      "source": "mobile",
      "document": {
        
        "mime_type": "application/pdf",
        "file_size": 1438781,
        "sha256": "TdxdgX8lBzV6/SYW96F/BEh19ob0eFAn4wKAWhWpUyk=",
        "file_name": "File_example.pdf",
        "link": "https://s3.eu-central-1.wasabisys.com/in-files/61371989950/pdf-b487668896662779cbdb29a3c29c0a9a-804713c25d2b57.pdf",
        "caption": "This is text with file",
        "filename": "File_example.pdf",
        "page_count": 14,
        "preview": "data:image/jpeg;base64,/9j/4AAQSkZJ.........."
      },
      "from": "919984351847",
      "from_name": "Gerald"
    }
  ],
  "event": {
    "type": "messages",
    "event": "post"
  },
  "channel_id": "MANTIS-M72HC"
}

Step-by-step instructions to obtain this file:

1) Capture the webhook from an incoming message or receive a message via an HTTP call; 2) Extract the Media ID from the corresponding media object; 3) Make the GET Media request to the following endpoint: GET /media/{media-id}

Example:

curl --request GET \
     --url https://gate.whapi.cloud/media/pdf-b487668896662779cbdb29a3c29c0a9a-804713c25d2b57 \
     --header 'accept: application/pdf' \
     --header 'authorization: Bearer <YOUR_API_TOKEN>'

Important Notes: The response body contains the actual file, not just a URL!

Method 2: Enable Auto Download and Use the File URL

Whapi.Cloud provides an optional setting that enables automatic uploading of incoming media to secure cloud storage. With this setting active, each incoming file includes a direct public link.

How to Enable It:

Go to your channel settings;
Enable the toggle: "Auto Download";

You can find detailed instructions in the article:

What Happens Next:

When a file is received, Whapi uploads it to cloud storage. The webhook payload will include a link parameter in the media object. The file is retained in the cloud for 30 days, after which it is deleted. .

How it works?

Enabling the setting will add the Link parameter to the JSON array, where you will immediately receive a direct link to the file:

The link to the media files processed by your number at the time of the enabled setting is bound to the message, which means that you will be able to get a link to the media file via API Call.

Conclusion

Whapi.Cloud offers two powerful methods to retrieve files from WhatsApp:

Use the Get Media endpoint when you want to control file retrieval manually.
Enable Auto Download for easier, automated access with public links.

Both approaches are developer-friendly and ensure you always get the original file in its correct format. - -

PreviousHTTP API NextRetrieve a Specific User's Chat History

Last updated 2 days ago

Was this helpful?