whatsmcp

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. A 1:1 message to a number that is NOT in this account's contacts is refused with reason recipient_not_contact so you do not message a stranger by accident; set force=true to send anyway (the gate does not apply to groups, channels, templates or Business numbers). 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 or a t.me/<name> link. A phone in +E.164 form works only if it is already in this account's Telegram contacts, and force does not change that. 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
`force`	No	set true to send a 1:1 message to a number that is NOT in this account's contacts; without it such a send is refused with reason recipient_not_contact so you do not message a stranger by accident. No effect on groups, channels, templates, Business (WABA) numbers or Telegram accounts
`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.

Changed1 schema field changedNov 2, 2026

changedOutput schema / properties / refusal / properties / account_status / description

Previous value: -"when the number is not working: its status — starting, not_running, whatsapp_down, suspended, pairing, unlinked or locked"New value: +"when the number is not working: its status — starting, not_running, whatsapp_down (telegram_down for a Telegram account), suspended, pairing, unlinked or locked"

Changed2 schema fields changedNov 1, 2026

changedInput schema / properties / force / description

Previous value: -"set true to send a 1:1 message to a number that is NOT in this account's contacts; without it such a send is refused with reason recipient_not_contact so you do not message a stranger by accident. No effect on groups, channels, templates or Business (WABA) numbers"New value: +"set true to send a 1:1 message to a number that is NOT in this account's contacts; without it such a send is refused with reason recipient_not_contact so you do not message a stranger by accident. No effect on groups, channels, templates, Business (WABA) numbers or Telegram accounts"

changedInput schema / properties / to / description

Previous 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"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 or a t.me/<name> link. A phone in +E.164 form works only if it is already in this account's Telegram contacts, and force does not change that. Never a bare number, which could be a phone or a user id"

Changed1 schema field changedOct 31, 2026

addedInput schema / properties / force

Added value: +{
+  "description": "set true to send a 1:1 message to a number that is NOT in this account's contacts; without it such a send is refused with reason recipient_not_contact so you do not message a stranger by accident. No effect on groups, channels, templates or Business (WABA) numbers",
+  "type": "boolean"
+}

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 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.6/5.0

Behavior5/5

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

Goes well beyond the annotations: discloses the recipient_not_contact refusal gate, the 24-hour Business window constraint, per-attachment size limits, caption behavior, and the meaning of each returned status including a warning against retrying queued sends (consistent with idempotentHint=false). This is exactly the extra context annotations cannot convey.

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 purpose and dense enough that nearly every clause carries information; length is justified by 16 parameters. It suffers slightly from being one long run-on paragraph with repeated force/limit statements that also appear in 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 16-parameter mutation tool with an output schema, the description covers everything an agent needs: recipient id conventions per backend, attachment constraints, the contact gate, template rules, and status interpretation. No meaningful gap remains for correct invocation.

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 baseline is 3, but the description adds real semantic grouping: the three mutually exclusive attachment types with their limits, template overriding text/attachments, and force having no effect on groups/channels/templates/Business/Telegram. Some of this duplicates schema text, but the cross-parameter interactions are new value.

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?

Opens with a specific verb+resource ('Send a message from one of your accounts') and immediately enumerates the media variants and Telegram backend case. It is clearly differentiable from siblings like wa_edit_message, wa_react, 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?

Gives concrete when-to-use conditions: templates for starting conversations or messaging outside the 24-hour window, force for non-contact recipients, and explicit 'do NOT send it again' on queued status. It names sibling tools (wa_list_accounts, wa_list_messages) for obtaining ids, though it does not route the agent away from this tool toward edit/react for modifying existing messages.

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?