download_media
Fetch, decrypt, and save media from a cached WhatsApp message to a local file, returning its path; small images and audio are also embedded for MCP clients.
Instructions
Fetch the encrypted media payload (image, video, audio, document) for a previously-cached message, decrypt it, and write it to a local file under the store directory; returns the absolute path. For image and audio downloads at most 5 MiB, the decrypted bytes are ALSO embedded in the tool result as an ImageContent or AudioContent block so remote MCP clients can view or hear the payload without accessing the daemon's filesystem. Videos and documents are not embedded (too large or not renderable inline). Optionally also writes the decrypted file to output_path, which must live under the configured media root (WHATSAPP_MCP_MEDIA_ROOT, default <store>/uploads/). If WhatsApp's CDN refuses the stored media link (HTTP 403/404/410, typical for media from history sync, whose signed links expire), the daemon asks the account's own phone once to re-upload the file, waits up to 30 seconds for its answer, downloads once more, validates the payload against the cached size and SHA-256, and only then stores the verified link; the phone must be online, and if it no longer has the file the call fails saying so. Recovery also works in read-only mode: the request goes only to the account's own phone, and no notification is sent to the sender or chat. Idempotent — repeated calls for the same message return the cached file path. Prerequisite: the message must contain media; use list_messages to find media message IDs. Returns a JSON object {Success, Message, MediaType, Filename, Path} as the first content block, followed by an optional ImageContent/AudioContent block for renderable media.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"message_id": "<message_id>",
"chat_jid": "<chat_jid>"
},
"name": "download_media"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| chat_jid | Yes | WhatsApp JID: individual as `<digits>@s.whatsapp.net` or bare phone digits, group as `<digits>-<timestamp>@g.us` | |
| message_id | Yes | WhatsApp message ID of a media message (use `message_id` from list_messages) | |
| output_path | No | optional absolute path under the configured media root (`WHATSAPP_MCP_MEDIA_ROOT`, default `<store>/uploads/`); parent directory must exist; an existing file is left untouched and the call succeeds only if it already holds identical media, otherwise it fails; omit to write only to the daemon cache |