WhatsMCP: MCP for WhatsApp

Send WhatsApp Message

wa_send_message

Send a WhatsApp message from one of your accounts — text, or an attachment: an image via image_base64 (JPEG/PNG, at most 5 MiB; text becomes the caption), a document via document_base64 (any file, at most 20 MiB; text becomes the caption), or audio via audio_base64 (at most 16 MiB; no caption). For a Business (WhatsApp Cloud API) number, set 'template' to send a pre-approved message template (e.g. hello_world) — the only way to start a conversation or to message that number outside the 24-hour window. Check the returned status: "sent" means delivered; "queued" means the message was accepted but not yet confirmed and may still arrive, so do NOT send it again; "refused" means nothing was sent and the reason explains whether retrying will help.

Input Schema

TableJSON Schema

Name	Required	Description
`to`	Yes	the recipient: a phone number in international form (digits only, e.g. 447700900123) for a 1:1 chat, or a full group/channel JID (…@g.us for a group, …@newsletter for a channel)
`text`	No	the message body; when an image is attached this is its caption and may be empty. Either text or image_base64 is required
`template`	No	optional: the name of a pre-approved message template to send (Business/WABA numbers only), e.g. hello_world. Use this to start a conversation or to message outside the 24-hour window; text and attachments are ignored when set
`audio_ptt`	No	optional: true to send as a voice note (push-to-talk) rather than a regular audio attachment
`account_id`	Yes	the account to send from, as returned by wa_list_accounts
`audio_mime`	No	optional: the audio's mime type, e.g. audio/ogg; codecs=opus
`image_mime`	No	optional: the image's mime type, image/jpeg or image/png
`audio_base64`	No	optional: base64-encoded audio to attach, at most 16 MiB decoded; audio has no caption
`image_base64`	No	optional: base64-encoded JPEG or PNG to attach, at most 5 MiB decoded; when set, text becomes the caption
`audio_seconds`	No	optional: the audio's duration in seconds
`document_mime`	No	optional: the document's mime type, e.g. application/pdf
`document_base64`	No	optional: base64-encoded document/file to attach, at most 20 MiB decoded; when set, text is the caption
`document_filename`	No	optional: the filename shown to the recipient, e.g. report.pdf
`template_language`	No	optional: the template's language/locale code, e.g. en_US; defaults to en_US
`template_variables`	No	optional: values that fill the template body's positional {{1}}, {{2}}, … placeholders, in order

Output Schema

TableJSON Schema

Name	Required	Description
`status`	Yes	sent (delivered), queued (accepted but unconfirmed - do NOT re-send), or refused (not attempted)
`refusal`	No	present only when status is refused
`message_id`	No	WhatsApp's id for the message, present only when status is sent
`request_id`	No	correlation id; a queued message appears in wa_list_messages under this id once it settles

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedOct 1, 2026

addedInput schema / properties / template

Added value: +{
+  "description": "optional: the name of a pre-approved message template to send (Business/WABA numbers only), e.g. hello_world. Use this to start a conversation or to message outside the 24-hour window; text and attachments are ignored when set",
+  "type": "string"
+}

addedInput schema / properties / template_language

Added value: +{
+  "description": "optional: the template's language/locale code, e.g. en_US; defaults to en_US",
+  "type": "string"
+}

addedInput schema / properties / template_variables

Added value: +{
+  "description": "optional: values that fill the template body's positional {{1}}, {{2}}, … placeholders, in order",
+  "items": {
+    "type": "string"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

First observedSep 17, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations only declare it is a non-readonly, non-idempotent, non-destructive write. The description goes well beyond that by decoding the returned status values ('sent' delivered, 'queued' accepted but unconfirmed — do NOT resend, 'refused' nothing sent with a reason) and by disclosing the size ceilings per attachment type. This is exactly the operational context an agent needs to avoid duplicate sends.

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?

Front-loaded with the core action, then attachment variants, then template rules, then status semantics — a sensible information hierarchy. It is a long single passage with heavy em-dash nesting, which costs some readability, but every clause carries a distinct fact.

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?

For a 15-parameter mutation tool with a rich schema and an existing output schema, the description covers the remaining judgment calls: which attachment to use and its limits, when template is mandatory, and how to interpret the result. Nothing needed to invoke it correctly is 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 already 100%, so the baseline is 3, but the description adds cross-parameter semantics the per-property schema does not state in one place: text becomes the image/document caption but is ignored when template is set, audio has no caption, and the attachment options are alternatives rather than additive. That coherent framing earns a point above baseline.

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?

States a specific verb (send) and resource (WhatsApp message) and enumerates supported variants (text, image, document, audio, template). It is immediately distinguishable from siblings like wa_edit_message, wa_react, or wa_delete_message, which also operate on messages but do different things.

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?

Gives clear conditional guidance: use template for Business/WABA numbers to start a conversation or message outside the 24-hour window, and explains the mutually exclusive attachment paths. It never names an alternative sibling tool or states an explicit 'do not use this when…', so it stops short of a 5.

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

All WhatsMCP: MCP for WhatsApp tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?