whatsmcp

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 14, 2026

addedOutput schema / properties / refusal / properties / account_status

Added value: +{
+  "description": "when the number is not working: its status — starting, not_running, whatsapp_down, suspended, pairing, unlinked or locked",
+  "type": "string"
+}

addedOutput schema / properties / refusal / properties / account_status_reason

Added value: +{
+  "description": "the detail of account_status, e.g. no_egress, stopped, no_plan",
+  "type": "string"
+}

addedOutput schema / properties / refusal / properties / since

Added value: +{
+  "description": "when the number stopped working, RFC3339, when known",
+  "type": "string"
+}

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 27, 2026

TDQS

A4.3/5.0

Behavior5/5

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

Annotations only say it is non-read-only, non-idempotent, non-destructive; the description goes well beyond them by explaining the sent/queued/refused status semantics and the critical warning not to resend a 'queued' message, which directly operationalizes the idempotentHint=false signal. It also discloses per-attachment size limits and caption behavior.

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?

One dense passage, front-loaded with the core action, then attachment modes, then the template rule, then status handling. Nothing is wasted, though the long em-dash chain makes it heavier to scan than a bulleted structure would be.

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

Completeness4/5

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

For a 15-parameter tool with an output schema, the description covers the risky areas an agent must know: template exclusivity, attachment limits, and result-status interpretation. Return-value shape is correctly left to the output schema, though template_variables usage could have been illustrated more concretely.

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

Parameters3/5

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

Schema coverage is 100% and parameter descriptions already document sizes, mime types, caption behavior, and template semantics, so the description largely restates what the schema provides. It adds the useful grouping of the three attachment modes and the 'text and attachments are ignored when template is set' interaction, but no syntax beyond that. Baseline 3 is appropriate.

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?

Specific verb (Send) plus resource (WhatsApp message) with the full modality space enumerated: text, image, document, audio, and template. It is immediately distinguishable from siblings like wa_edit_message or wa_react without opening the schema.

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 and as the only way to start a conversation or message outside the 24-hour window. It does not explicitly name sibling alternatives (e.g. wa_edit_message for corrections), so it stops just short of the top band.

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

All whatsmcp 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?