Skip to main content
Use this endpoint to download media files received via WhatsApp messages. When a contact sends your business an image, audio clip, video, or document, WhatsApp stores the file and provides a media_id in the incoming message payload. Pass that ID to this endpoint to retrieve the actual file content.

​
Endpoint

​
Authentication

​
Path Parameters

​
string
required
Your Convo project ID.

​
Request Body

​
string
required
The media ID of the file you want to retrieve. This value is found in incoming message webhook payloads (e.g., message.image.id, message.audio.id, message.document.id) or in the response from the Get Message Details endpoint.
​
string
The format in which the media content is returned. Accepted values:
  • "arraybuffer" (default) — Returns the raw binary data as an array buffer. Suitable for saving files to disk or processing binary content in server-side code.
  • "json" — Returns a JSON object containing a signed download URL or media metadata.
  • "text" — Returns the media content as a plain text string.
  • "stream" — Returns the media as a readable stream. Suitable for piping data to a file or HTTP response.

​
Request Example

​
Response

The response format depends on the responseType you specify: For json mode:
​
boolean
Returns true when the media was successfully retrieved in JSON mode.
Media IDs are obtained from incoming message payloads delivered via webhooks. When a contact sends a media message (image, audio, video, or document), the webhook payload includes a field such as message.image.id or message.document.id. Note that media IDs expire after a short period — download the media promptly after receiving the ID.

​
Error Responses