whatsmcp

Set Webhook

wa_set_webhook

[Not usable in this workspace: it acts on every number, and not every number's plan includes it — calling it returns a plan_required refusal; wa_get_plan lists each number's plan.] Register an HTTPS endpoint to receive WhatsApp events as they happen, so you do not have to poll wa_list_messages. By default it delivers inbound messages; pass events to also receive outbound messages (sent from your number), message delivery status (delivered/read/failed), account lifecycle events (connected, disconnected, unlinked, blocked), and call events (completed, missed). Returns a signing secret that is shown ONCE — store it immediately. Calling this again replaces the endpoint and issues a NEW secret.

Input Schema

Name	Required	Description	Default
`url`	Yes	an https:// URL that will receive POSTed events; must be publicly reachable
`events`	No	which events to receive — any of message.inbound, message.outbound, message.status, account.connected, account.disconnected, account.unlinked, account.blocked, call.completed, call.missed; defaults to message.inbound

Output Schema

Name	Required	Description
`url`	No
`events`	No
`secret`	No	the signing secret — shown ONCE; store it now, it cannot be retrieved later
`refusal`	No	present only when the request was declined
`warning`	No
`webhook_id`	No
`verification`	No
`test_delivery`	No

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 changedOct 30, 2026
- addedOutput schema / properties / test_delivery
```
Added value: +{
+  "type": "string"
+}
```
- addedOutput schema / properties / warning
```
Added value: +{
+  "type": "string"
+}
```

Changed1 schema field changedOct 26, 2026

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

changedInput schema / properties / events / description

Previous value: -"which events to receive; defaults to message.inbound"New value: +"which events to receive — any of message.inbound, message.outbound, message.status, account.connected, account.disconnected, account.unlinked, account.blocked, call.completed, call.missed; defaults to message.inbound"

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"
+}

First observedSep 27, 2026

TDQS

A4.3/5.0

Behavior5/5

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

Goes well beyond the annotations: discloses the plan_required refusal and workspace limitation, the one-time signing secret, and that re-calling replaces the endpoint and issues a NEW secret — the key consequence of idempotentHint=false. Default event scope (inbound only) is also disclosed. Minor tension with destructiveHint=false since existing config and secret are overwritten, but this is disclosed rather than contradicted.

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 workspace/plan caveat is front-loaded in brackets before the core behavior, which is the right priority, and every sentence carries information (default scope, event taxonomy, secret handling, replacement semantics). It is dense but not padded; the bracketed note is slightly long relative to the rest.

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 an output schema present, the description need not detail return values, yet it still flags the one-time secret that matters operationally. Combined with the URL reachability requirement, event defaults, and plan limitation, an agent has everything needed to invoke it correctly.

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, but the description adds real meaning: it explains that omitting events yields inbound messages only and that each event category maps to outbound messages, delivery status, lifecycle, and call events. This lets an agent choose events without reverse-engineering the enum list.

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

Purpose4/5

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

States a specific verb and resource: registers an HTTPS endpoint to receive WhatsApp events, explicitly framed as an alternative to polling wa_list_messages. The sibling set contains wa_get_webhook, wa_delete_webhook, and wa_enable_webhook, none of which are named or distinguished here, so an agent must infer how 'set' relates to 'enable'.

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 a clear use case (receive events as they happen instead of polling) and a hard exclusion (returns plan_required in this workspace, check wa_get_plan). It does not address when to prefer wa_enable_webhook or what happens if a webhook already exists beyond 'calling this again replaces the endpoint'.

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?