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.

Remember that you can get information about the message not only from the webhook, but also by executing the HTTP request “Get message”.

Let's see what this Media ID looks like using the example of an incoming message webhook:

Webhook Example (Message with PDF document)

{
  "messages": [
    {
      "id": "tGZmYoiXecvbKahzwpwKmg-gEcTwl0rVw",
      "from_me": false,
      "type": "document",
      "chat_id": "[email protected]",
      "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"
}

As we can see, in this example, the Media ID looks like this: "id": "pdf-b487668896662779cbdb29a3c29c0a9a-804713c25d2b57"

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} The body of the response will contain the file itself.

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!

What does this mean? It means that services such as Readme.io and other visual test shells will not allow you to save the file when you make a request.

Use Postman or your IDE to save the file from the response body.

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:

1

Go to your channel settings.

On your channel page, open the channel settings by clicking on the "Settings" button.

Click on Settings for your channel

2

Enable the toggle: "Auto Download".

Select the file types for which you would like to receive direct links.

The type of files that will be uploaded to the cloud to obtain a direct link

Don't forget to save your selected settings.

You can find detailed instructions in the article: Setting Auto Download

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. Read more about file storage periods.

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:

With the "Auto Download" setting enabled, you get 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.

Remember that you can get information about the message not only from the webhook, but also by executing the HTTP request “Get message”.

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.