Check if the WhatsApp session is connected and working.

Returns the session status (WORKING, STOPPED, etc.), the connected phone number, and display name. Use this to verify connectivity before sending messages.

No parameters required.

Returns:

• name: Session name

• status: "WORKING" if connected, "STOPPED" if disconnected

• phone: Connected phone number (if authenticated)

• pushName: Display name on WhatsApp

Get information about the authenticated WhatsApp account.

Returns the phone number, display name, and WhatsApp ID of the connected account. Use this to verify which account is connected.

No parameters required.

List recent WhatsApp chats with last message preview and profile pictures.

Returns chat IDs, names, profile picture URLs, and a preview of the last message. Use the chat ID from results to read messages with whatsapp_read_messages.

Args:

• limit: Number of chats to return (1-100, default 20)

• offset: Pagination offset (default 0)

Returns array of chats with:

• id: Chat ID (use this in other tools)

• name: Contact or group name

• picture: Profile picture URL (may expire)

• lastMessage: Preview with body, from, fromMe, hasMedia, timestamp

• lastMessageAt: ISO timestamp of last message

Read messages from a specific WhatsApp chat.

Returns messages with sender, text content, timestamp, and message ID. Use the message ID from results for whatsapp_react or reply_to in whatsapp_send_text.

Powered by Message Store — persistent full history with full-text search and sender filtering.

Args:

• contactId: Phone digits for a person ("5521986910666"; survives @c.us↔@lid flips), or group JID "*@g.us". Look up via whatsapp_list_contacts.

• limit: Number of messages to return (1-100, default 20)

• offset: Skip N messages for pagination (default 0)

• search: Full-text search within this chat's messages (optional)

• sender: Filter by sender name or JID (optional)

• type: Filter by message type: chat, image, album (optional)

• since: ISO date — messages after this date (optional)

• until: ISO date — messages before this date (optional)

• fromMe: Filter sent (true) or received (false) messages (optional)

• downloadMedia: Include media download URLs when falling back to live (default false)

• markAsRead: Mark messages as read after fetching (default false)

Returns:

• messages: Array with id, sender, body, timestamp, type, fromMe, hasMedia

• total: Total matching messages

• hasMore: Whether more results exist

Send a text message to a contact (person or group).

CORE tier supports text messages only (no images, video, audio, or documents). A rate limit delay is enforced between sends to avoid WhatsApp detection.

Args:

• contactId: Contact id: phone digits for a person (e.g. "5521986910666"; survives @c.us↔@lid flips), or a group JID "*@g.us". Look up via whatsapp_list_contacts.

• text: Message text to send

• replyTo: Optional message ID to quote-reply to (get from whatsapp_read_messages)

Returns:

• status: "sent"

• messageId: The sent message's ID

• contactId: Where it was sent

React to a WhatsApp message with an emoji.

Use an empty string for the reaction to remove an existing reaction.

Args:

• contactId: Contact id: phone digits for a person (e.g. "5521986910666"; survives @c.us↔@lid flips), or a group JID "*@g.us". Look up via whatsapp_list_contacts.

• messageId: Message ID to react to (get from whatsapp_read_messages)

• reaction: Emoji to react with (e.g., "👍", "❤️", "😂"). Empty string removes reaction.

Returns confirmation of the reaction.

Edit a previously sent text message.

Only works on messages you sent (fromMe=true). WhatsApp shows an "edited" label on the message after editing.

Args:

• contactId: Contact id: phone digits for a person (e.g. "5521986910666"; survives @c.us↔@lid flips), or a group JID "*@g.us". Look up via whatsapp_list_contacts.

• messageId: Message ID to edit (must be your own message)

• text: New text content

Returns confirmation with the edited message ID.

Delete (unsend) a message from a contact's chat.

Removes the message for everyone. WhatsApp shows "This message was deleted" in its place.

Args:

• contactId: Contact id: phone digits for a person (e.g. "5521986910666"; survives @c.us↔@lid flips), or a group JID "*@g.us". Look up via whatsapp_list_contacts.

• messageId: Message ID to delete

Returns confirmation of deletion.

Forward a message from one chat to another contact.

The forwarded message shows a "Forwarded" label in WhatsApp and preserves the original sender attribution.

Args:

• contactId: Contact id: phone digits for a person (e.g. "5521986910666"; survives @c.us↔@lid flips), or a group JID "*@g.us". Look up via whatsapp_list_contacts. — destination

• messageId: Message ID to forward (get from whatsapp_read_messages)

Returns confirmation with forwarded message ID.

Check if a phone number is registered on WhatsApp.

Use this before sending a message to a number not yet in your address book.

Args:

• phone: Phone number with country code, no spaces or dashes (e.g., "5511999999999")

Returns:

• numberExists: true if registered on WhatsApp

• contactId: The id to use as contactId in other tools (the same phone digits)

Unified address book — lists people you DM and groups you're in.

Use the returned 'id' as contactId in any chat-targeting tool (send_text, read_messages, etc.):

• Person: id = phone digits (universal — survives @c.us↔@lid flips)

• Group: id = group JID (e.g. "120363...@g.us")

Args:

• kind: "person" | "group" | "all" (default "all")

• search: Filter by name or id (optional)

• limit: Maximum rows to return (1-100, default 20)

• offset: Pagination offset for the persons section (default 0)

Returns array of contacts with:

• kind: "person" | "group"

• id: phone digits or group JID — pass to other tools

• name: display name (Google Contact name → push name → phone/jid fallback)

• messageCount, lastMessageAt: activity stats

• For persons: pushName, googleName, email, organization

• For groups: memberCount

Detail for a single contact — person OR group, by stable id.

Returns shape depends on kind:

• Person: contact (phone, names, email, org), all chats they appear in, all JID variants, message stats.

• Group: chat (group metadata), members with display names, member_count.

Args:

• contactId: phone digits (person; "5521986910666"), or "*@g.us" (group). Look up via whatsapp_list_contacts.

Download media (image, audio, video, document) from a WhatsApp message.

Fetches the media attached to a specific message and returns it directly:

• Images: returned inline so Claude can see them

• Audio: returned inline so Claude can process them

• Video/documents: saved to /tmp/whatsapp-media/ and path returned

Use whatsapp_read_messages first to find messages with hasMedia=true, then pass the contactId and messageId here.

Note: Old media (weeks+) may no longer be available on WhatsApp's servers.

Args:

• contactId: Phone digits or "*@g.us" — the contact whose chat contains the message

• messageId: Message ID with media to download (from whatsapp_read_messages)

Returns:

• For images: the image content directly (Claude can see it)

• For audio: the audio content directly

• For other files: file path where it was saved + metadata

Transcribe a WhatsApp voice message or audio to text.

Server-side transcription via Speaches (Whisper). Optionally replies to the original message with the transcription text.

Args:

• contactId: Phone digits or "*@g.us" — the contact whose chat contains the audio

• messageId: Message ID of the audio to transcribe

• replyWithTranscription: If true, sends the transcription as a WhatsApp reply to the audio message (default false)

Returns:

• transcription: The transcribed text

• language: Detected language (if available)

• replyMessageId: ID of the reply message (if replyWithTranscription=true)

Search across all WhatsApp message history. Supports full-text search, date ranges, sender filtering, and message type filtering.

Args:

• search: Text to search for (case insensitive, supports Portuguese/unicode)

• contactId: Scope search to one contact (phone digits or "*@g.us") (optional)

• sender: Filter by sender name or JID (optional)

• since: ISO date string — messages after this date (optional)

• until: ISO date string — messages before this date (optional)

• type: Message type filter: chat, image, album, e2e_notification (optional)

• fromMe: Filter sent (true) or received (false) messages (optional)

• limit: Results per page (1-100, default 20)

• offset: Pagination offset (default 0)

Returns:

• messages: Array with id, chatJid, senderName, body, timestamp, messageType, fromMe

• total: Total matching messages

• has_more: Whether more results exist

Note: sender_name may be null for some messages.

Get social graph for a WhatsApp contact — shared groups, mutual connections.

Args:

• phone: Phone number with country code (e.g., "5524999160115")

Returns:

• groups: Groups this contact is in, with message counts

• mutualContacts: Other contacts who share groups with this person

Get a readable summary of recent messages in a WhatsApp chat, including sender names and timestamps.

This is optimized for readability — use whatsapp_read_messages for structured data with filtering, or whatsapp_search_messages for full-text search.

Args:

• contactId: Phone digits for a person, or "*@g.us" for a group

• limit: Number of recent messages to include (1-200, default 50)

Returns:

• chat: Name, type, message count, date range

• messages: Recent messages with sender name, body, timestamp, type

Overview dashboard of WhatsApp activity — message totals, top chats, top contacts, and group/DM breakdown.

No arguments needed. Returns:

• Totals: messages, contacts, chats, groups, DMs

• Activity: messages today, this week

• Top 5 chats by message count (name may be null for groups — use whatsapp_get_contact to look up)

• Top 5 contacts by message count

Import a WhatsApp chat export file (ZIP or TXT) into the message store.

Use this to backfill historical messages from WhatsApp's "Export Chat" feature. Only inserts new messages — won't overwrite or duplicate existing data.

The file should be a WhatsApp chat export:

• ZIP file containing a .txt (standard WhatsApp export format)

• Or a plain .txt file

The chat name is extracted from the filename (e.g., "Conversa do WhatsApp com NAME.zip"). You can override it with the chatName parameter.

Messages are matched to existing contacts by name. If a contact doesn't exist, it's created. If the chat already exists in the store (by name), messages are added to it.

Args:

• filePath: Absolute path to the ZIP or TXT file on the server

• chatName: Optional override for the chat name (extracted from filename if omitted)

Returns:

• chat_name: Resolved chat name

• total_parsed: Number of messages found in file

• inserted: New messages added

• skipped_duplicates: Messages already in store

• senders: List of sender names found

Enable auto-reply with audio transcription for a contact.

When the contact sends a voice note, the transcription is sent back as a quoted reply automatically. DM only — voice notes in groups are never auto-replied even if a member is flagged.

The flag is contact/phone-scoped, so it follows the contact across WhatsApp's @c.us → @lid JID transitions automatically — no need to re-flag when WhatsApp migrates the JID.

Args:

• phone: Phone number digits only, no @, no spaces (e.g., "5521986910666"). Look up via whatsapp_list_contacts first if you only know the name.

Returns:

• status: "ok" on success

• phone: the canonical phone

• enabled: true

Disable auto-reply with audio transcription for a contact.

Args:

• phone: Phone number digits only, no @, no spaces (e.g., "5521986910666").

Returns:

• status: "ok"

• phone: the canonical phone

• enabled: false

List every contact that currently has auto-reply transcription enabled, with display names from Google Contacts (when matched) or WhatsApp push name fallback.

Returns:

• contacts: array of { phone, display_name, person_name, push_name }