WhatsMCP: MCP for WhatsApp

Load Older Messages

wa_load_history

Ask the account's phone for older messages in one conversation, before the oldest one stored here, and store them. The phone must be online; it usually answers within seconds. Read the result with wa_get_chat and the same chat. Loaded messages are history: they never trigger webhooks and appear in wa_list_messages only with include_history=true. They are kept for your plan's history window like any other message. A conversation needs at least one stored message to page back from.

Input Schema

Name	Required	Description
`chat`	Yes	the conversation to page back: a phone number for a direct chat, or a group JID (…@g.us)
`count`	No	how many older messages to ask the phone for, 1-500; defaults to 50
`account_id`	No	the account, as returned by wa_list_accounts; omit it when the workspace has only one account

Output Schema

Name	Required	Description
`status`	Yes	ok (the request reached the phone) or refused (nothing was asked)
`refusal`	No	present only when status is refused
`answered`	Yes	the phone answered in time; false means it may still answer later (it must be online) — read the chat again in a minute
`imported`	Yes	of those, how many were new here; 0 with answered=true usually means you reached the start of what the phone holds
`received`	Yes	messages the phone sent back

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedOct 26, 2026

changedInput schema / properties / account_id / description

Previous value: -"the account, as returned by wa_list_accounts"New value: +"the account, as returned by wa_list_accounts; omit it when the workspace has only one account"

changedInput schema / required

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

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

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

AddedSep 25, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Annotations only say it writes, is non-idempotent and non-destructive; the description adds the real behavioral facts: the phone must be online, it usually answers within seconds, loaded messages never trigger webhooks, and they fall inside the plan's history window. That is exactly the context an agent needs before invoking.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, front-loaded with the action and the online requirement, followed by how to read the result and the retention semantics. No filler.

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?

Covers the offline/latency caveat, the webhook-invisibility caveat, the visibility flag needed elsewhere, retention, and the prerequisite. With an output schema and annotations present, nothing an agent needs is missing.

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% – chat format, count range/default and account_id fallback are all documented in the schema. The description adds only lightweight framing ('one conversation', 'before the oldest one stored'), so baseline 3 applies.

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 and resource: fetch older messages for one conversation from the account's phone and store them. The phrase 'before the oldest one stored here' precisely distinguishes it from wa_list_messages and wa_get_chat, which only read what is already stored.

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 routing: read the result with wa_get_chat using the same chat, and load with include_history=true to see it in wa_list_messages. It also names the prerequisite (at least one stored message to page back from). It does not explicitly say when not to call it (e.g. when the phone is likely offline), but the context is clear.

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?