Block a contact so they can no longer send the paired user messages or see your last seen, profile photo, or status; the blocked contact is not explicitly notified but will see undelivered messages on their side. Idempotent if already blocked. Reversible via unblock_contact. Returns the plain-text string Blocked <jid>.

Create a new WhatsApp group with the given name and initial participants; the paired user becomes admin and listed participants receive a you were added system message in the new chat. Reversible by calling leave_group (irreversible itself) or update_group_participants with remove. Returns a JSON object {jid, info} where jid is the new group's JID and info is the freshly-fetched group metadata.

Revoke (delete-for-everyone) a message; recipients see a message was deleted notice and the local cache row is marked revoked. Permanent — there is no undo, and the original body cannot be restored once revoked. You can only delete your own messages unless you are a group admin. Use edit_message instead when you only want to correct text. Returns the plain-text string Message deleted on success.

Fetch the encrypted media payload (image, video, audio, document) for a previously-cached message, decrypt it, and write it to a local file under the store directory; returns the absolute path. Optionally also writes the decrypted file to output_path, which must live under the configured media root (WHATSAPP_MCP_MEDIA_ROOT, default <store>/uploads/). No notification is sent to the sender or chat. Idempotent — repeated calls for the same message return the cached file path. Prerequisite: the message must contain media; use list_messages to find media message IDs. Returns a JSON object {Success, Message, MediaType, Filename, Path}.

Edit a previously-sent text message in place; recipients see the new body with an edited label. Only your own messages can be edited and only within WhatsApp's edit window (~15 minutes). Re-edit by calling again with another new_body; to remove the message entirely use delete_message (revoke). Returns the plain-text string Message edited on success.

Fetch the paired user's current WhatsApp blocklist from the server. Read-only; blocked contacts are not notified by this call. Use block_contact / unblock_contact to mutate the list. Returns a JSON document with the list of blocked JIDs.

(reads local cache; works while disconnected) Fetch metadata for a single cached chat by JID. Read-only; no side effects. Use list_chats to discover chat JIDs, or get_group_info for live group metadata. Returns a JSON object describing the chat (JID, name, last-message metadata when requested), or the JSON literal null when the chat is not in the cache.

Fetch live group metadata (subject, topic, participants with admin flags, announce/locked settings, invite config) for the given group JID. Read-only; no side effects. Use list_groups to discover which groups exist. Returns a JSON object describing the group.

Return a group's current invite link, or revoke and mint a fresh one when reset=true. Warning: reset=true permanently invalidates the previous link — anyone holding a previously-shared copy can no longer use it to join, and there is no undo. Prerequisite: admin. Use join_group_with_link to consume an invite. Returns a JSON object {link} containing the active invite URL.

(reads local cache; works while disconnected) Fetch a specific cached message and the surrounding messages in its chat. Read-only; no side effects. Use list_messages for searching across many chats. Returns a JSON object with the target message and arrays of messages before and after it.

(reads local cache; works while disconnected) Return the current vote tally for a cached poll. Read-only; no side effects. Zero-vote options are included so the response always lists every original option. Returns a JSON object {poll_message_id, chat_jid, tally} where tally is option_label -> vote_count.

Fetch the paired user's current WhatsApp privacy settings from the server. Read-only; no side effects. Use set_privacy_setting to change individual values. Returns a JSON document with keys like groupadd, last, status, profile, readreceipts, online, calladd, messages, defense, stickers and their current string values.

Report whether the embedded WhatsApp bridge is connected and which account it is paired with. Read-only; no side effects. Call this first when other tools fail with auth or connection errors. Returns a JSON object {connected, paired, own_jid?, own_phone?, hint?} — hint includes the URL of the local pairing UI when not yet paired.

Query WhatsApp servers to check which of the supplied phone numbers are registered on WhatsApp; the queried users are not notified. Read-only with no chat side effects. Use before send_message when you only have a phone number and need to confirm the contact exists. Returns a JSON object keyed by input phone, each value {is_in: bool, jid: string, verified_name?: string} (or similar).

Join a WhatsApp group via a chat.whatsapp.com/<code> invite URL or the bare invite code; existing members see a joined via invite link system message and the new chat appears for the paired user. Reversible via leave_group (which is itself permanent). Use get_group_invite_link to mint or read invite links. Returns a JSON object {jid} containing the joined group's JID.

Leave a WhatsApp group; remaining members see a you left system message and the paired user loses access to all future messages in the chat. Permanent — to rejoin you must be re-added by an admin or invited via a fresh link (join_group_with_link). Prefer setting privacy or muting on the client if you only want silence. Returns the plain-text string Left group <chat_jid>.

(reads local cache; works while disconnected) List cached WhatsApp chats (1:1 and group), optionally filtered by name substring and sorted by recency or alphabetic name. Read-only; no side effects. Use get_chat for a single chat by JID, list_groups for groups only. Returns a JSON array of chat objects (each with JID, name, last-message metadata when requested).

List every WhatsApp group the paired user is currently a member of, fetched live from WhatsApp. Read-only; no side effects. Use get_group_info for detailed metadata about one specific group. Returns a JSON array of group-info objects (each with JID, subject, participants, settings, and so on).

(reads local cache; works while disconnected) Search and page through cached WhatsApp messages, optionally filtering by chat, sender, time range, and substring; can include surrounding context messages. Read-only; no side effects. Use get_message_context to expand around a single known message ID, or request_sync to backfill missing history. Returns a human-readable formatted text block listing matching messages.

Ack the most recent incoming messages in a chat to clear its unread badge; senders receive read receipts (subject to their privacy settings). Cannot be unread once acked. Use mark_read for ack-by-message-ID. Returns the plain-text string Acked N message(s) in <chat_jid>.

Mark specific incoming messages as read; senders receive read receipts (subject to their privacy settings) and the chat's unread badge decrements. Cannot be unread once acked. Use mark_chat_read to clear the unread badge for an entire chat without enumerating message IDs. Returns the plain-text string Marked N message(s) read in <chat_jid>.

Ask WhatsApp servers to backfill historical messages for a chat into the local cache; messages arrive asynchronously and become queryable via list_messages once delivered. No effect on the chat itself or other users. If from_timestamp is omitted, the request anchors on the newest cached message. Returns a plain-text confirmation describing what was requested.

(reads local cache; works while disconnected) Search the cached WhatsApp contact list by case-insensitive substring of name or phone number. Read-only; no side effects. Use is_on_whatsapp to verify whether an unknown phone number is registered. Returns a JSON array of contact objects (each with JID, push name, full name, and phone).

Send an audio file as a WhatsApp voice note (waveform UI, push-to-play); non-ogg inputs are transcoded via ffmpeg before upload. Reversible via delete_message (revoke). Use send_file when you want the audio delivered as a regular attachment instead of a voice note. Prerequisites: ffmpeg must be on PATH for non-ogg inputs. Returns a JSON object {Success, Message, ID} where ID is the WhatsApp message ID on success.

Send a WhatsApp contact card; recipients see a tappable contact entry they can save to their address book and the outgoing message is persisted to the local cache. When vcard is omitted a minimal vCard 3.0 is synthesised from name + phone. Reversible via delete_message (revoke). Returns a JSON object {Success, Message, ID} where ID is the WhatsApp message ID on success.

Upload and send a picture, video, document, or raw audio attachment via WhatsApp; the recipient sees a media message and the outgoing row is persisted to the local cache. Reversible via delete_message (revoke). For voice notes use send_audio_message (which transcodes to ogg/opus); for plain text use send_message. Returns a JSON object {Success, Message, ID} where ID is the WhatsApp message ID on success.

Send a new WhatsApp text message to a person or group; recipients see it as a fresh message from the paired account and the row is also stored in the local cache. Reversible via delete_message (revoke) or edit_message (correct text); to quote a previous message use send_reply, for emoji acknowledgement use send_reaction. Returns a JSON object {Success, Message, ID} where ID is the WhatsApp message ID on success.

Send a new WhatsApp poll message with 2 to 32 options; recipients see a votable poll card and an outgoing row plus poll metadata is persisted locally so votes can be tallied. Reversible via delete_message (revoke). Use send_poll_vote to cast votes and get_poll_results to read tallies. Returns a JSON object {Success, Message, ID} where ID is the poll message ID on success.

Cast or re-cast a vote on a previously-seen poll; each call replaces the caller's prior vote on that poll, and the new tally is broadcast to the chat. Reversible by calling again with the desired option set (or an empty list to clear). Prerequisite: the poll must be in the local cache, i.e. send_poll was used or we received the poll via sync. Returns a JSON object {Success, Message, ID} where ID is the vote message ID.

Set the paired user's own global online availability; contacts permitted by privacy settings see online or last-seen accordingly. Reversible by calling again with the inverse state. Use send_typing for per-chat composing/recording indicators instead. Returns a JSON object {success, message}.

Add or replace an emoji reaction on an existing message; recipients see the small emoji badge attached to the original message. Reversible by calling again with an empty emoji string (clears the reaction); for a fresh message use send_message and for a quoted reply use send_reply. Returns the plain-text string Reaction sent on success.

Send a text message that visibly quotes a previous message; recipients see the new text with the quoted message attached. Reversible via delete_message (revoke) or edit_message (correct text). Use send_message for a fresh non-quoting message and send_reaction for an emoji acknowledgement. Returns the plain-text string Reply sent on success.

Show or hide the per-chat typing or recording presence indicator; the recipient sees a transient typing... or recording audio... hint that auto-expires after roughly 25 seconds. Reversible by calling again with active=false. Use send_presence to set global online/offline availability instead. Returns the plain-text string Presence active for <chat_jid> or Presence paused for <chat_jid>.

Toggle announce-only mode on a group; when enabled, non-admin send attempts are rejected by WhatsApp servers and members see a system message about the change. Reversible by calling again with the inverse value. Prerequisite: admin. See set_group_locked for restricting metadata edits. Returns the plain-text string Group <chat_jid> announce_only=<bool>.

Toggle locked mode on a group; when enabled, only admins can change name/topic/icon and members see a system message about the change. Reversible by calling again with the inverse value. Prerequisite: admin. See set_group_announce for restricting who can post. Returns the plain-text string Group <chat_jid> locked=<bool>.

Change a group's display name (its subject); members see a system message naming the new subject. Reversible by calling again with the previous name. Prerequisite: admin (or non-locked group). Returns the plain-text string Group <chat_jid> renamed to "<name>".

Change a group's description/topic; members see a system message indicating the description was updated. Reversible by calling again with the previous text or with an empty string to clear. Prerequisite: admin (or non-locked group). Returns the plain-text string Group <chat_jid> topic updated.

Change a single WhatsApp privacy knob (read-receipts, last-seen, online, group-add, etc.) for the paired account; takes effect immediately and may change who can see your activity or contact you. Reversible by calling again with the previous value (capture it via get_privacy_settings first). Not every name/value combination is valid — WhatsApp rejects invalid combinations server-side. Returns a JSON document echoing the updated settings.

Update the paired user's WhatsApp profile About text; contacts permitted by privacy settings see the new text on the profile screen. Reversible by calling again with the previous text or with an empty string to clear. Note: this is the static profile About line, not the temporary Status story feed. Returns a JSON object {success, message}.

Unblock a previously blocked contact, restoring their ability to message the paired user and see your last seen/profile/status; the contact is not notified. Idempotent if already unblocked. Reversible via block_contact. Use get_blocklist to see who is currently blocked. Returns the plain-text string Unblocked <jid>.

Add, remove, promote, or demote participants of a group; the chat shows a system message naming each affected participant. Reversible by calling again with the inverse action (add ↔ remove, promote ↔ demote). Prerequisite: the paired user must be a group admin. Returns a JSON object describing the per-participant outcome.