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.

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, when a message last arrived, 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).

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.

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).

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 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).

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.

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.

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.

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.

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.

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.

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.

Case-insensitive text search over the messages wazap holds locally — all chats, or one chat. It cannot reach messages the phone never synced to this device.

The complete message behind a message_id, including the quoted message it replies to, its reactions, and its media metadata. Use it after search_messages or read_messages when you need the context around a single message.

Find contacts by name or phone number (substring match on the name, digit match on the number). Returns contact_id values usable as chat_id.

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.

Full details for one contact: name, number, about text, profile picture URL, whether they are a saved contact, a business, or blocked.

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.

Call this before manage_group: most group actions need admin rights.

Download the photo/video/audio/document attached to a message and save it to disk on the machine running wazap. Images of 1 MB or less are also returned inline so you can look at them.

Fails with MEDIA_UNAVAILABLE when WhatsApp has expired the file.

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.

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.

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 poll. Does not send. Participants vote in WhatsApp; wazap cannot read the votes back. Show the preview; after the user says yes, call confirm_send.

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.

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.

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

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.

Send a draft created by send_message, send_media, send_poll, send_location or forward_message. This is the only call that reaches WhatsApp. The draft is consumed. A missing or expired draft_id means draft again and show the new preview before calling this.

Retract a message. DESTRUCTIVE and visible to everyone in the chat — confirm with the user first. Only works on messages the linked account sent, and only within 2 days of sending.

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.

Change the state of a chat: archive/unarchive, pin/unpin, mute/unmute (mute_hours defaults to 8), mark_read (sends read receipts) or mark_unread.

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.

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

• get_invite_link / revoke_invite_link

Everything except leave requires the linked account to be a group admin; call get_group_info first to check.