io.github.razvangirgiz/wazap

Send a draft created by send_message, send_media, send_poll, send_location or forward_message. This is the only call that reaches WhatsApp, and it sends a draft at most once: confirming it again answers the same receipt with already_sent: true. Only the MCP session that created the draft may confirm it. After reinitializing or reconnecting with a new session, draft again and obtain fresh user approval. A missing or expired draft_id also means draft again and show the new preview before calling this. SEND_OUTCOME_UNKNOWN means WhatsApp may have the message: check the chat with read_messages before anything else, and never draft it again without asking the user.

Create a group with the given name and participants; the linked account becomes the owner. Each participant comes back with a status: ok, invite_needed (their privacy settings require an invite link) or failed.

Delete a message. DESTRUCTIVE — confirm with the user first. for_everyone is required, and picks one of two different deletes; tell the user which: - for_everyone: true retracts it for everyone in the chat. Works on messages the linked account sent, within 2 days of sending. In a group where the linked account is an admin it also takes someone else's message, deleted as an admin; anywhere else that is NOT_OWN_MESSAGE. - for_everyone: false removes it from the linked account's own devices only: anyone's message, at any age. Nobody else sees a change.

Download the photo/video/audio/document attached to a message and save it to disk on the machine running wazap. The file at `path` is already decrypted — open or process it as is; nothing else is needed. Images of 1 MB or less are also returned inline so you can look at them. The structured result carries: `path` (the saved file), `mime`, `size` (bytes), `filename` (the name it was saved under — a timestamped name wazap made, not the sender's), `original_filename` (the name the sender's file had, or null when the envelope carried none), `caption` (the text the sender wrote under the media, or null — audio and voice notes cannot carry one), `message_id` and `sender` (the same identity fields as search_messages — is_saved, contact_name, pushname, name_source — or null when even the message can no longer be read back). The id resolves in its raw form too: `false_<lid>@lid_<stanza>` works whether or not the chat's number was ever learned — when it was, the lid spelling finds the same message filed under the paired number. An unresolved sender never blocks the file. Without `account_id` the same lookup walks every linked account's store in turn before failing, and the result's `account_id` names the one that served the file. Fails with MEDIA_UNAVAILABLE when WhatsApp has expired the file.

Replace the text of a message the linked account sent. WhatsApp only allows this within 15 minutes of sending; after that send a correction instead.

Draft a forward of an existing message to another chat. Does not send. The recipient will see it marked as forwarded. Show the preview; after the user says yes, call confirm_send.

Full details for one contact: name, number, about text, profile picture URL, whether they are a saved contact, a business, or blocked. `name_source` says where the shown name comes from — "contact" when it is the saved address-book name (is_my_contact), "pushname" when it is a name the person publishes, or "none" when there is no usable name.

Details of a group: name, description, owner, creation date, whether only admins may post, whether the linked account is an admin, and the participant list (up to 500; participant_count is always the true total). The invite link is included only when the linked account is an admin. The settings come too: info_locked (only admins edit the name, description and photo), member_add_mode ("admins" or "all"), join_approval, disappearing_seconds (0 when off), and community ({is_community, parent_group_id}) when the group is a community or belongs to one. Call this before manage_group: most group actions need admin rights.

The complete message behind a message_id, including the quoted message it replies to, each reaction with who left it, who chose each option of a poll or answered an event, and its media metadata. Use it after search_messages or read_messages when you need the context around a single message. On the user's own messages, `delivery.status` says how far it got ("sent", "delivered", "read", "played", "pending" or "error"), and in a group `read_by` and `delivered_to` name who, with the time. It stops at "delivered" or is missing when read receipts are off on either side, and large groups may send none. The id also resolves in its raw form: `false_<lid>@lid_<stanza>` works even when the chat's number was never learned, and an id that names the same message under the lid or the paired number finds it either way. With several accounts linked and no `account_id`, an id the resolved account cannot find is tried on each of the others in turn before MESSAGE_NOT_FOUND comes back, and the answer's `account_id` names the one that had it; pass `account_id` to keep the lookup on one account. The `sender` carries the same identity fields as search_messages: `id` (the canonical jid — a `…@lid` only while WhatsApp has never revealed the paired number), `phone` (the number, or null for an unresolved lid), `is_saved` (whether the sender is in the user's address book), `contact_name` (the name saved there, or null), `pushname` (the name the sender publishes, when that is the name `name` shows) and `name_source` ("contact", "pushname" or "none" — which of those `name` came from).

Everything that happened recently, grouped by chat. This is the catch-up tool: one call instead of list_chats plus a read_messages per chat. WhatsApp's own notices — device linking, group membership changes, encryption notices — are left out so the counts are conversation; pass include_system to see them. A chat lists at most its newest 2,000 messages of the window.

Check the session: connection status ("connected" means the tools work, "not_linked" means the user must run `npx wazap-mcp login`), whether the initial history sync has finished, which account is linked, how fresh the local history is — `history` shows when a message last arrived and flags `stale` when the phone has been quiet for a day while connected — the versions and data directory in use, and how many contacts carry a name from the phone's address book (contacts_named: 0 means it never arrived). `webhook.delivery` counts the account's webhook events: delivered (last 7 days), failed and cancelled (last 30), pending; a non-zero `consecutive_failures` or `retrying` means the receiver is refusing or unreachable right now, and `last_failure` says how. Call this whenever another tool reports NOT_CONNECTED, NOT_LINKED or SYNC_IN_PROGRESS, or to confirm which account you are about to send from. Without account_id the top-level fields are the default account, plus `accounts` listing every live one. While a link is in progress the status is "linking" and `pairing` carries the code the user still has to type into their phone.

The stories (status updates) the linked account has received in the last N hours, newest first, each with its author, its text or caption and its time. WhatsApp keeps a story for a day and so does wazap; nothing older is held. With include_previews the photos come as small images, and download_media works on a story's message_id like on any message. Stories never appear in chats, catch-ups or waits; this is the only place they show.

Chats where the last word is theirs and it asks for something: a question, a request ("poți", "te rog", "can you", "when"…), or a voice note nobody has heard yet. A conversation that ended in "ok, thanks" is not listed, and neither is an ask older than max_age_hours (two weeks by default): that one was abandoned, not left waiting. Groups count only when the user was @-mentioned or replied to after their own last message. A [business] account's ask is often an automatic reply; weigh it accordingly. People come first, then the oldest wait. Each entry quotes the ask, says how many of their messages arrived since the user's last one, and how long they have been waiting. This is the follow-up half of an inbox triage; use get_recent_messages for what happened, and this for who is still waiting.

Join a group from an invite: a link (https://chat.whatsapp.com/<code>, or the code alone) as invite, or the message_id of an invite message someone sent (type "invite"). Exactly one of invite / message_id. Without confirm: true it joins nothing and returns the group's name, description, member count and whether an admin must approve new members. Show that to the user and wait for an explicit yes, then call again with the same invite or message_id and confirm: true. Every member sees the account join. The answer is the group's chat_id, or pending_approval when an admin must let the account in first.

Read this FIRST, before any other WhatsApp tool. Returns the guide to the tools, the id formats, the recommended workflows, the message shape and every error code with what to do about it. Takes no arguments and never touches WhatsApp.

Pair this wazap with the user's WhatsApp when get_status says not_linked, logged_out, session_corrupt or auth_failure. Ask the user for their phone number in international format, call this, and show them the code it returns with these exact steps: WhatsApp → Settings → Linked devices → Link a device → Link with phone number instead → enter the code. Then call get_status every 10 seconds until it says connected (up to 3 minutes). The code expires; call this again for a fresh one if get_status goes back to not_linked with an error. The account must already exist (`wazap account add`). Pass account_id when more than one is configured. An unknown id is ACCOUNT_NOT_FOUND. Never call this when the account is already linked.

List every configured WhatsApp account: id, name, connection status, masked phone, owner name, and whether that account allows writes. Call this first when more than one account is linked, then pass account_id on the other tools. Takes no arguments besides the optional account_id (ignored for the listing).

List conversations, most recently active first. Use it to discover the chat_id values the other tools need. Each chat has: chat_id, name, type, unread_count, last_message {text, timestamp, from_me}, archived, pinned, muted_until, and left (groups you are no longer in).

Change a chat, or a message in it. Actions: - archive / unarchive, pin / unpin (the chat), mute / unmute (mute_hours defaults to 8), mark_read (sends read receipts) / mark_unread - pin_message / unpin_message — need message_id; pins it for everyone in the chat, for pin_hours 24, 168 (default) or 720 - star_message / unstar_message — need message_id; the star is the linked account's own - clear — DESTRUCTIVE, empties the chat for the linked account only - delete — DESTRUCTIVE, deletes the chat for the linked account only - block / unblock — a person's chat only; a blocked person can no longer message or call the account A message_id must belong to chat_id. Every action hits WhatsApp at once and there is no draft: say what will change and wait for a yes before calling it.

Administer a group. Actions: - add / remove / promote / demote — need participant_ids; each participant comes back with status ok, invite_needed or failed - leave — DESTRUCTIVE, rejoining needs an invite - set_subject / set_description — need value - set_picture — needs exactly one of file_path / url: JPEG, PNG or WebP, at most 10 MB. Every member sees it at once and there is no draft: show the image and wait for a yes first - remove_picture — takes the group photo down; ask first the same way - get_invite_link / revoke_invite_link - list_join_requests — who is waiting for approval, with when and how they asked - approve_join_requests / reject_join_requests — need participant_ids from list_join_requests; each comes back with status ok or failed - set_announcement_only / set_info_locked / set_join_approval — value "on" or "off" - set_add_mode — value "admins" or "all" - set_disappearing — value "off", "24h", "7d" or "90d" Everything except leave requires the linked account to be a group admin; call get_group_info first to check. Every change is visible to all members at once: say what will change and wait for a yes before calling it.

The user dealt with what this chat was asking, outside WhatsApp or by a reply wazap did not see: a phone call, a meeting, a decision. The open ask is remembered as handled and the chat leaves get_unanswered. The next message from the other side makes a new ask and the chat comes back on its own. Kept on this machine only; nothing is sent or marked read on WhatsApp.

Add an emoji reaction to a message, or pass an empty string to remove your reaction.

Read messages from one chat, oldest to newest. Without `before` you get the most recent messages. Pass `before` (the oldest message_id you already have) to page further back; wazap asks the phone for older history when the local store runs out, which takes a few seconds.

Search by meaning and by words at once over the whole WhatsApp history — answers "the invoice Dan mentioned", "the address Ana sent", "what did they say about the trip". A paraphrase or another language still hits through its meaning, and a short or foreign-language question still hits through its words; the two rankings are fused. A match found by meaning weighs a little less with age (85% a month on, never under 70%), so the fresher of two close matches comes first but a clearly closer old one still does; one chat takes at most three leading places before other chats' hits, and a near-duplicate trails the list. For an exact string — an id, a phone number, a URL — search_messages is the better tool. Each result carries its date, a fused score, `matched` ("words", "meaning" or "both") and the cosine `similarity` when its meaning ranked it. chat_id, since, until and from narrow the search exactly like search_messages — including a name that resolves to exactly one person. A hit marked "index only" is a message wazap holds only as text: quote its words; get_message returns them, but download_media has nothing to open and it cannot be replied to or forwarded. A hit found only by meaning must clear the similarity floor, so a question with no answer comes back empty; when only weak meaning matches survive, the output says so — do not present them as found facts. When semantic recall is off or its embedding setup is missing, the tool does not dead-end: it falls back to a keyword search over the local history, marked `mode: "keyword_fallback"`, and `recall_unavailable.fix` names the command that turns semantic recall on. An error remains only when even the fallback cannot run. Each hit's `sender` carries the same identity fields as search_messages, and `freshness` says whether the local history may be partial or stale. Every answer also declares its window: the semantic path reports how many messages the index covers, and a keyword fallback carries the same `coverage`…

Take a person out of the account's WhatsApp contacts: the saved entry and its name go, the chat and its history stay. Nothing is sent to the contact.

Save a person in the account's WhatsApp contacts: a new entry for a phone number, or a new name for an existing one. The name syncs to every linked device, and with save_on_phone (default) also into the phone's own address book. WhatsApp keeps no other fields — email, "my accountant" and the like go to set_contact_note, which stays on this machine.

Find contacts by name, phone number, tag or detail: a substring match on the name, a digit match on the number, or a word from a local tag or detail — so "contabil" finds the person filed under role: contabil by update_contact_details. With only tag it lists everyone carrying that tag. Returns contact_id values usable as chat_id.

Substring search over the messages wazap holds locally — all chats, or one chat, including history synced on first link. Case and diacritics are ignored ("sedinta" finds "ședință"). Every message the phone synced to this device is kept and searched; there is no per-chat window. It cannot reach messages the phone never synced to this device. Every answer declares the window it searched: `coverage.searched` counts the held messages in scope (the chat scope and time filters applied) and `coverage.oldest_at`/`newest_at` bound that window, so "no messages found" always says how much history was searched. `coverage.per_chat_cap` is null: no chat is capped. A query so short or so common that the search reaches its scan limit answers `scan_capped: true` and `searched_back_to`: messages older than that were not searched, so narrow it (chat_id, since/until, a longer query) before concluding nothing exists. `from` accepts "me", a phone number, a contact/chat id, or a name: a name must resolve to exactly one person — it matches contact names, notify names and last-seen pushnames, then one-to-one chat display names — or the error lists the candidates it found. Every message's `sender` carries `id` (the canonical jid — a `…@lid` only while WhatsApp has never revealed the paired number), `phone` (the number, or null for an unresolved lid), `is_saved` (the sender is in the user's address book — when false, treat the shown name as claimed, not known), `contact_name` (the name saved there, or null), `pushname` (the name the sender publishes, when that is the name `name` shows; null for saved contacts and unnamed senders) and `name_source` ("contact", "pushname" or "none" — which of those `name` came from). A sender wazap knows nothing about reads "unknown (lid …1234)" — never bare lid digits, which look like a phone number and are not one. `freshness` says whether the history this searched may be partial (sync still running) or stale (nothing inbound for 24h while connected); on…

Draft a map pin, optionally labelled with a place name and address. Does not send. Show the preview; after the user says yes, call confirm_send.

Draft an image, video, audio file, document or GIF, from a local path on the machine running wazap or from a public URL. Does not send. Exactly one of file_path / url. Maximum 100 MB. Show the preview; after the user says yes, call confirm_send. A GIF is sent with as_gif: an mp4 goes out looping, a .gif is converted to mp4 first (needs ffmpeg on the machine running wazap).

Draft a text message. Does not send. Returns a draft_id and a preview of the recipient and exact text. Show that preview to the user; after they say yes, call confirm_send. A draft lasts 15 minutes. To @-mention people, pass mention_ids and write @<number> in the text where each mention belongs, the digits of their id (@40722123456). A mention the text lacks gets its @<number> added at the end, so the preview is the text that goes out.

Draft a poll. Does not send. Participants vote in WhatsApp, and their votes show on the poll message: read_messages counts them and get_message says who chose each option. Show the preview; after the user says yes, call confirm_send.

Remember something about a person, on this machine only: "Hermi, my own agent", "the accountant", "always answers late". The note then rides along wherever the contact shows: list_chats, search_contacts, get_contact, get_recent_messages and get_unanswered. Nothing is sent to WhatsApp and the contact never sees it. An empty note removes it.

Set the linked WhatsApp account's own profile picture from a local path on the machine running wazap or from a public URL. Exactly one of file_path / url. JPEG, PNG or WebP only, at most 10 MB. DESTRUCTIVE and visible to every contact. Show the image and wait for a yes first. This call hits WhatsApp immediately; there is no draft.

Ask WhatsApp to send the linked phone's address book from scratch, and wait up to 15 seconds for it. Nothing on WhatsApp changes: this only refills wazap's own contact list. Use it when get_status reports contacts_named: 0, or when senders in a group read as phone numbers for people you know are saved on the phone. Returns named_before and named_after so you can tell whether it helped; if both are 0 the phone has no saved contacts for these people.

Turn a voice note or an audio message into text. The transcript is cached, so a second call on the same message costs nothing, and from then on the message reads as [voice message · 0:42] "what was said" in read_messages, get_recent_messages and get_message, and its words become searchable through search_messages. What it costs depends on how the user set transcription up: the local provider (whisper.cpp) is free and the audio never leaves the machine, while the API provider uploads the audio to a third-party service and is billed per minute. Either way this is capped at 10 calls a minute. TRANSCRIBE_UNAVAILABLE means transcription is off or unfinished on this machine; the fix names the command the user has to run. Do not retry it.

File local, searchable details on a person: tags like "client" or "echipa", and key-value fields like {"role": "contabil", "oras": "Cluj"}. This is how "the accountant" or "all suppliers" resolve later — search_contacts matches tag and field text, and its tag filter lists everyone carrying one. Nothing is sent to WhatsApp: the contact never sees it and the phone is unchanged. A field set to "" is deleted; remove_tags / remove_fields take keys away. Pass at least one of the four edits. The person need not be a saved contact.

Block until a message arrives, then return it, or return empty when the timeout passes. This is how an agent stays on the line without polling: call it in a loop, and pass the cursor it returns into the next call so nothing that landed between two calls is missed. The first matching message starts a one-second settle so a burst comes back together. Only messages from other people are returned, never the user's own, and never WhatsApp's system notices. With addressed_to_me, only direct messages, group messages that @-mention the user, and replies to the user's own messages wake the wait; everything else in a group is ignored. A cursor from a previous run of wazap cannot be honoured: the wait then starts from now and says cursor_reset. The timeout is capped at 55 seconds because MCP clients give up at 60.