WhatsMCP: MCP for WhatsApp

Send WhatsApp Message

wa_send_message

Send a message from one of your accounts (WhatsApp, or Telegram for an account whose backend is telegram) — 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

Name	Required	Description
`to`	Yes	the recipient. WhatsApp: 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). Telegram (an account whose backend is telegram): the chat id exactly as wa_list_messages reports it (<id>@telegram; a group is -<id>@telegram, a channel or supergroup -100<id>@telegram) to reply, or to start a conversation an @username, a t.me/<name> link or a phone in +E.164 form — never a bare number, which could be a phone or a user id
`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`	No	the account to send from — the account_id on the message row you are replying to, or from wa_list_accounts; omit it when the workspace has only one account
`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

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

changedInput schema / properties / account_id / description

Previous value: -"the account to send from, as returned by wa_list_accounts"New value: +"the account to send from — the account_id on the message row you are replying to, or from wa_list_accounts; omit it when the workspace has only one account"

changedInput schema / required

Previous value: -[
-  "account_id",
-  "to"
-]New value: +[
+  "to"
+]

addedOutput schema / properties / refusal / properties / candidates

Added value: +{
+  "description": "on an account_ambiguous refusal: the accounts to choose from — retry with one of these as account_id",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "account_id": {
+        "description": "the id to retry with as account_id",
+        "type": "string"
+      },
+      "name": {
+        "description": "the account's WhatsApp display name",
+        "type": "string"
+      },
+      "phone": {
+        "description": "the account's phone number, E.164",
+        "type": "string"
+      },
+      "status": {
+        "description": "whether the number works right now — live, connecting, or why not, as wa_list_accounts reports it",
+        "type": "string"
+      }
+    },
+    "required": [
+      "account_id"
+    ],
+    "type": "object"
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}

Changed1 schema field changedOct 26, 2026

changedInput schema / properties / to / description

Previous value: -"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)"New value: +"the recipient. WhatsApp: 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). Telegram (an account whose backend is telegram): the chat id exactly as wa_list_messages reports it (<id>@telegram; a group is -<id>@telegram, a channel or supergroup -100<id>@telegram) to reply, or to start a conversation an @username, a t.me/<name> link or a phone in +E.164 form — never a bare number, which could be a phone or a user id"

Changed3 schema fields changedOct 11, 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 17, 2026

TDQS

A4.4/5.0

Behavior5/5

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

With only readOnly/idempotent/destructive hints from annotations, the description adds critical behavioral context the annotations cannot convey: the meaning of 'sent', 'queued' (accepted but not confirmed — do NOT resend), and 'refused' (nothing sent, reason indicates retry viability). It also discloses per-attachment size limits and caption behavior, which directly affect how the agent should call it.

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 description is front-loaded with the core action and modes, then details, then status semantics. It is dense but earns most of its length given 15 parameters and multi-backend behavior; a few phrases overlap with the schema.

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 complex, high-parameter-count mutation tool, the description covers the essential modes, restrictions (template windows, size limits), and the crucial return-status handling. An output schema exists, so the extra status explanation is bonus rather than a gap-filler.

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 description coverage is 100%, so the schema already documents every parameter in detail, setting the baseline at 3. The description reinforces the attachment parameters (sizes, caption semantics) but adds little beyond what the schema already states.

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 states a specific verb and resource ('Send a message from one of your accounts'), enumerates the supported message modes (text, image, document, audio, template), and covers both WhatsApp and Telegram backends. It is clearly distinguishable from siblings like wa_edit_message, wa_list_messages, and wa_create_template.

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 gives strong usage context: template for Business numbers is 'the only way to start a conversation or to message that number outside the 24-hour window', and status handling tells the agent not to resend on 'queued'. However, it doesn't explicitly compare against alternatives such as wa_edit_message for corrections or wa_react for reactions.

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?