Most automation around a WhatsApp message stops at sending. This one reads the chat back to prove it landed.

It means a second pass over the macOS accessibility tree found a rendered message bubble whose text contains what the automation just pasted. Concretely, after the Return key event is posted, handleSendMessage in Sources/WhatsAppMCP/main.swift waits 1.0 second, calls traverseAXTree(pid:) again, and iterates every AXGenericElement that has a description starting with 'Your message, '. For each match it strips the trailing time pattern (regex ,\s+\d{1,2}:\d{2}\s*[APap][Mm]) and lowercases. The tool returns verified: true only when one of those readbacks contains the input or the input contains the readback. If the AX tree has no such node, verified is false and the response includes a warning field with whatever the last 'Your message, ' bubble actually said. Verification is part of the call, not a separate webhook, which is why the model can decide to retry on the same turn rather than queueing a follow-up.

Because input on macOS Catalyst apps is most reliable through Cmd+V, and the only way to deliver the message text to the compose field without losing emoji or non-ASCII characters is to put it on the clipboard first. pasteText() at lines 225 to 237 of main.swift starts by reading NSPasteboard.general.string(forType: .string) and storing the result, then clears the pasteboard, sets the message, posts a Cmd+V keyboard event, sleeps 0.35 seconds for the paste to land, and restores the original clipboard contents. The window in which a human's clipboard is overwritten is at most a few hundred milliseconds, and the original contents are put back even if the send itself fails. Without this discipline, every send would silently overwrite whatever the user had just copied, and that is the kind of bug that makes people uninstall an automation tool the second time it bites them.

Two specific helpers in main.swift. saveCursorPosition() at line 195 reads NSEvent.mouseLocation, accounts for the screen-Y flip on the primary NSScreen, and returns a CGPoint. clickAt() saves that point before posting the mouse-down/mouse-up events and then posts a CGEvent of type mouseMoved back to the saved point as the last act of the click. The cursor returns to the place the user left it, frame by frame. For modifier keys, sendKeyEvent() flushes keycodes 55, 56, 58, and 59 (left and right Cmd, Shift, and Option) with isolated key-up events both before and after any flag-bearing event. Without that flush, a Cmd+V posted by the automation could leave the OS believing Cmd is still down, and the human's next keystroke would be misinterpreted as part of a shortcut. These are not features. They are the cost of sharing the same physical input devices with a human user.

No. The server has no HTTP client targeting Meta. It binds to the WhatsApp Desktop macOS Catalyst app by its bundle id net.whatsapp.WhatsApp (line 57 of main.swift), launches it via /usr/bin/open if it is not already running, and drives it through AXUIElement calls. There is no API key, no access token, no template list, and no 24-hour messaging window. The env block in the MCP host configuration is literally an empty object. The only authority the server needs is the operating system's Accessibility permission, granted to the host process (Claude Code, Cursor, or whichever client forks it as a stdio child) in System Settings, Privacy and Security, Accessibility.

AXUIElementSetMessagingTimeout(appElement, 5.0) is called on the WhatsApp application AX element at line 120 of main.swift, immediately after AXUIElementCreateApplication(pid). That timeout governs every accessibility call that follows: requesting children, fetching attributes, posting clicks. If WhatsApp Desktop fails to respond within 5.0 seconds, the call errors out cleanly rather than blocking the model's turn. The number is hardcoded; there is no flag to lengthen it. In practice a healthy WhatsApp window responds in tens of milliseconds, so the ceiling only trips when the window is minimised, the OS is under heavy load, or accessibility was just regranted and the TCC database is stale. When you see verified: false despite a successful paste, the first thing to check is whether one of the AX traversals timed out; the stderr log from the child will tell you.

No. There is no whatsapp_create_chat tool in the surface. The eleven exposed tools are status, start, quit, get_active_chat, list_chats, search, open_chat, scroll_search, read_messages, send_message, and navigate (assembled into the allTools array at line 1110 of main.swift). search returns indexed buttons that are already in the sidebar's chats and contacts sections; open_chat clicks one of them. If the recipient is not in your sidebar, the agent sees nothing to click. This scoping is intentional: it means the automation cannot perform a cold outreach on your behalf, which keeps the tool aligned with personal use rather than broadcast.

It looks like a JSON object of shape {success: true, verified: false, to: "Alex", message: "...", warning: "Could not verify message appeared in chat. Last sent message: ..."}. success is true because the paste and Return key both succeeded; verified is false because the post-send AX traversal did not find a matching 'Your message, ' bubble. The warning includes the most recent outgoing message text the server did find, which is often the previous one if the new message has not rendered yet. The right caller behaviour is to wait briefly and call whatsapp_get_active_chat again to read the latest messages; if the new text now appears, the send did land. If after a second check the text is still absent, retry the send. Do not retry blindly on the first false: a duplicate send is worse than a slow render.

Browser automation of WhatsApp Web has a documented bad reputation for this exact use case because the message input is a contenteditable element rather than a textarea, so the usual Playwright or Selenium type() helpers do not deliver characters reliably; emoji and non-Latin scripts are particularly brittle. Focus management is fragile, paste events on contenteditable behave differently than on text inputs, and the page is a heavy SPA that re-renders on every websocket frame, which makes any selector-based check race against the rerender. The macOS Catalyst path bypasses all of that by talking to the same accessibility framework that VoiceOver and other assistive tech use; the AX tree settles after each user-visible change, so the post-send readback observes a stable state. The instructions block at the bottom of main.swift explicitly warns the model not to fall back to browser automation if accessibility fails, because the failure mode there is silent corruption rather than loud refusal.