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.

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.

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.

Send a text message. This is a REAL message from the user's own account and there is no undo — confirm the recipient and the wording with the user before sending anything sensitive.

Send an image, video, audio file or document, from a local path on the machine running wazap or from a public URL. Exactly one of file_path / url. Maximum 100 MB.

Send a poll to a chat. Participants vote in WhatsApp; wazap cannot read the votes back, so ask the user to report the outcome.

Send a map pin to a chat, optionally labelled with a place name and address.

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.

Forward an existing message to another chat. The recipient sees it marked as forwarded.

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.

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.