Skip to main content
Glama
mcp-whatsapp

mcp-whatsapp

download_media

Idempotent

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

NameRequiredDescriptionDefault
chat_jidYesWhatsApp JID: individual as `<digits>@s.whatsapp.net` or bare phone digits, group as `<digits>-<timestamp>@g.us`
message_idYesWhatsApp message ID of a media message (use `message_id` from list_messages)
output_pathNooptional 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

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.7.2
    • changedInput schema / properties / output_path / description
      Previous value: -"optional absolute path under the configured media root (`WHATSAPP_MCP_MEDIA_ROOT`, default `<store>/uploads/`); parent directory must exist; calls are skipped if the file already exists; omit to write only to the daemon cache"New value: +"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"
  2. Changed2 schema fields changedv0.3.0
    • changedInput schema / properties / message_id / description
      Previous value: -"WhatsApp message ID"New value: +"WhatsApp message ID of a media message (use `message_id` from list_messages)"
    • addedInput schema / properties / output_path
      Added value: +{
      +  "description": "optional absolute path under the configured media root (`WHATSAPP_MCP_MEDIA_ROOT`, default `<store>/uploads/`); parent directory must exist; calls are skipped if the file already exists; omit to write only to the daemon cache",
      +  "type": "string"
      +}
  3. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (readOnly=false, idempotent=true, destructive=false, openWorld=true) it discloses the 5 MiB inline-embedding rule for image/audio, the CDN 403/404/410 recovery path with a 30-second phone round-trip and online requirement, size and SHA-256 validation, read-only-mode recovery with no sender notification, and idempotent cache returns. This is exactly the kind of behavioral context annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core action and return shape are front-loaded in the first sentence and the paragraph is information-dense rather than padded. It is still one very long block covering embedding, recovery, and idempotency, which would scan better as separate sentences or bullets.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description supplies the return contract ({Success, Message, MediaType, Filename, Path} plus an optional ImageContent/AudioContent block) and covers failure modes, permissions, and network dependency. Nothing an agent needs to call this correctly appears to be missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by explaining that output_path lives under the configured media root and that omitting it writes only to the daemon cache while the cached path is returned either way. It restates rather than extends the chat_jid/message_id semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise verb chain — fetch, decrypt, write — naming the exact resource (encrypted media payload of a previously-cached message) and the output (absolute path). It is clearly distinguishable from siblings such as send_file or transcribe_audio.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states the prerequisite (the message must contain media) and routes the agent to list_messages to find media message IDs, and it explains when output_path is worth supplying. It stops short of naming an explicit alternative tool or a when-not-to-use case, so it falls just under a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.