Query WhatsApp data: conversations, contacts, messages, transcriptions, labels, and communities. Supports listing, searching, filtering, and looking up by ID.

IMPORTANT: Multiple WhatsApp accounts may be connected (e.g. personal + business). Always query entity="session" FIRST to see all connected accounts and their session IDs. Then use target_session to route queries to the correct account. Each account has different conversations, contacts, and messages.

HOW TO READ MESSAGES: To get messages from a specific conversation, pass its id (e.g. "5491157390064@c.us"). This returns the conversation info WITH its messages. Use limit to control how many. Do NOT use entity="messages" for this — that is for global text search only.

AUDIO TRANSCRIPTIONS: To get audio transcriptions, use entity="transcriptions" with an optional query. Or pass a conversation id to see messages (audio messages include transcription text).

Examples: List sessions: { entity: "session" } List conversations: {} Target specific account: { entity: "conversations", target_session: "sess_abc123" } Read messages: { id: "5491157390064@c.us" } Read last 100 msgs: { id: "5491157390064@c.us", limit: 100 } Search globally: { query: "meeting" } Search in chat: { id: "5491157390064@c.us", query: "meeting" } Unread conversations: { unread: true } Search contacts: { query: "Alice", entity: "contacts" } List labels: { entity: "labels" } Filter by label: { label: "Important", entity: "conversations" } List communities: { entity: "communities" } Filter by community: { community: "My Community", entity: "conversations" } Find which groups a contact is in: { id: "5491157390064@c.us", entity: "contacts", include_participants: true } List members of a group: { entity: "contacts", group: "120363421729019499@g.us" }

Get or generate a summary of a conversation

Manage WhatsApp Business labels. Requires a WhatsApp Business account.

Actions: add - Add a label to a conversation (requires label_name/label_id + conversation_id) remove - Remove a label from a conversation (requires label_name/label_id + conversation_id) create - Create a new label (requires label_name) delete - Delete a label (requires label_name or label_id)

Manage contact notes. Requires a WhatsApp Business account with notes enabled.

Actions: get - Read the note for a contact set - Write/update the note for a contact

Download media content (image, video, audio, document, sticker) from a WhatsApp message. Returns base64-encoded media data with metadata.

Get message_id from query results. The message must be a media message.

Examples: Download an image: { message_id: "true_123@c.us_3EB0...", conversation_id: "123@c.us" }

Manage chat state: archive, unarchive, mark as read/unread, pin, unpin, mute, unmute, set/clear draft.

Actions: archive - Archive a conversation unarchive - Unarchive a conversation mark_read - Mark a conversation as read mark_unread - Mark a conversation as unread pin - Pin a conversation (max 3 pinned) unpin - Unpin a conversation mute - Mute notifications (use mute_duration for duration) unmute - Unmute notifications set_draft - Set a draft message in the compose box (requires text) clear_draft - Clear the draft message

Manage personal reminders. Reminders are stored in the cloud and trigger notifications via the Kaption extension.

Actions: list - List all reminders get - Get a specific reminder by ID create - Create a new reminder (requires title + datetime) update - Update a reminder (requires id, optional title/datetime) delete - Delete a reminder (requires id) complete - Mark a reminder as completed (requires id) uncomplete - Mark a reminder as not completed (requires id)

Examples: List all: { action: "list" } Create: { action: "create", title: "Follow up with client", datetime: "2026-03-07T14:00:00Z" } Complete: { action: "complete", id: "rem_abc123" }

Schedule WhatsApp messages to be sent automatically at a specific time, in one of two modes: bot (default) - sent from Kaption's WhatsApp number, not the user's own. Stored in Kaption's cloud and sent even when this computer is off. One-to-one chats only (no groups); one line, max 800 characters. local ("From this computer") - sent from the user's own WhatsApp number, as them, while this computer and WhatsApp are open. Stays on this device. Kaption keeps it within safe limits automatically (a few messages an hour and a day, minutes apart, only to chats where the other person has written, at most 3 a day to groups) and refuses what does not fit. The only mode that can send to groups (ones the user can post in and posted in within 30 days). Text only. A message whose time passes while this computer is off is missed, never sent late on its own. The local mode must first be turned on by the user in Kaption (its "From this computer" option, after reading the risks); an assistant cannot turn it on. A refused local request says why and ends with a reason code, e.g. "(reason: per-day)".

Actions: list - List scheduled messages of both modes (each has "mode"); pass mode to list only one get - Get a specific scheduled message by ID create - Schedule a new message (requires message + datetime + conversation_id) update - Change the message and/or datetime (requires id) delete - Cancel/delete a scheduled message (requires id); in local mode it cancels a waiting message and removes a finished one cancel - Local mode only: cancel a waiting, missed or failed message remove - Local mode only: remove a finished message from the list send_now - Local mode only: send a missed or failed message now (still within the limits) Pass mode "local" for every action on a local message.

Examples: List all: { action: "list" } Schedule (Kaption bot): { action: "create", message: "Hey, just following up!", datetime: "2026-03-07T09:00:00Z", conversation_id: "5491157390064@c.us" } Schedule from the user's own number: { action: "create", mode: "local", message: "Running 10 min late", datetime: "2026-03-07T09:00:00-03:00", conversation_id: "5491157390064@c.us" } Schedule to a group: { action: "create", mode: "local", message: "Standup moved to 10", datetime: "2026-03-07T09:00:00Z", conversation_id: "120363000000000000@g.us" } Cancel: { action: "delete", id: "msg_abc123" }

Manage personal chat lists (custom lists). These are the personal account equivalent of Business labels. Lists allow organizing chats into custom categories like "Family", "Work", etc. Not available on all accounts — check with action "list" first to see if lists are enabled.

Actions: list - List all custom lists (also shows if feature is enabled) get - Get a list and its associated chats (requires id or name) create - Create a new list (requires name, optional conversation_id for initial chats) edit - Edit a list name or replace its chats (requires id or name) delete - Delete a list (requires id or name) add_chat - Add conversation(s) to a list (requires id/name + conversation_id) remove_chat - Remove conversation(s) from a list (requires id/name + conversation_id)

Examples: List all: { action: "list" } Create: { action: "create", name: "Family", conversation_id: ["number@c.us"] } Add chat: { action: "add_chat", name: "Family", conversation_id: "number@c.us" }

List WhatsApp contacts from the encrypted DBR3 cache (no network). Results are deduplicated by phone number — the same person across multiple labels collapses to one row. Saved contacts sort before unsaved, then alphabetically by display name. WhatsApp "@lid" privacy identifiers (opaque, non-dialable) are always excluded — only real phone-backed contacts are returned.

Examples: All contacts: {} Saved contacts only: { is_my_contact: true } Search by name: { query: "Maria" } Page 2 of 50: { limit: 50, offset: 50 }

Look up a single WhatsApp contact by JID or phone number. Pass either parameter — both work. If multiple raw contacts share the same phone (label dupes), the saved variant wins.

Examples: By JID: { jid: "5491155550001@c.us" } By phone with +: { phone: "+5491155550001" } By phone bare: { phone: "5491155550001" }

List the WhatsApp groups a specific contact participates in. Reads from cached chat metadata — no network.

Examples: Groups for contact: { jid: "5491155550001@c.us" }

List all WhatsApp groups the user belongs to. Reads from the cache — no network. For a live snapshot of a single group, use get_group (it forces a fresh GroupMetadata.update).

Examples: All groups: {} Search by group name: { query: "family" } Top 10: { limit: 10 }

Fetch a single group with a LIVE participant list. Forces Store.GroupMetadata.update() against the WA backend before reading, so the result reflects current membership including recent joins/leaves. Use this when accuracy matters; use list_groups for browsing.

Examples: Live group fetch: { jid: "120363421729019499@g.us" }

Export all WhatsApp contacts as CSV (RFC 4180) or JSON. Deduped, sorted alphabetically by display name. Default format is CSV. JSON projects the requested fields. Available fields: jid, phone, name, pushname, is_my_contact, is_business. WhatsApp "@lid" privacy identifiers (opaque, non-dialable) are always excluded — only real phone-backed contacts are returned.

Examples: CSV all fields: { format: "csv" } JSON name + phone: { format: "json", fields: ["name", "phone"] } Filtered CSV: { format: "csv", query: "Argentina" } Saved contacts only: { format: "csv", is_my_contact: true }

Get HTTP REST API connection info for programmatic access without MCP overhead. Returns URL, auth token, and available endpoints.

Get WhatsApp analytics data: KPIs, activity patterns, rankings, response times, call stats, labels, emojis, words, countries, and more. Supports section-based drill-down, date range filtering, chat/label/community filters, pagination, and chat/contact exports.

Start with section="overview" (default) for a compact summary, then drill into specific sections.

Sections: overview — High-level summary with top 5 chats (~5KB) kpis — Core + account KPIs + account overview activity — Daily/hourly/weekday/monthly + sent/received + message types rankings — Top chats/groups/DMs/senders (paginated) response_times — Avg/median/fastest/slowest + by-hour + by-chat calls — Call statistics (total/answered/missed/video/voice) labels — Labels (business) or Lists (personal) with chat counts emojis — Top emojis (paginated) words — Top words (paginated) countries — Contact country distribution silences — Longest-inactive chats channels — Newsletter/channel details + subscriber counts communities — Community details + sub-groups conversation_starters — Who starts conversations, night msgs, unanswered streaks — Current/longest streak + last active date gaps — Conversation gaps (>1 day silence periods) organization — Pinned/archived/muted/unread chat lists chat_detail — Full analytics for ONE specific chat (requires chat_id) export_chat — Export chat messages in format (requires chat_id + format) export_contacts — Export contacts in format (requires format) community_growth — Community member count history over time channel_growth — Channel subscriber count history over time

Examples: Overview: {} Rankings: { section: "rankings", chat_type: "group", limit: 5 } Filter by label: { section: "activity", label: "Family" } Chat detail: { section: "chat_detail", chat_id: "120363406792713578@g.us" } Export CSV: { section: "export_chat", chat_id: "...", format: "csv", limit: 100 } Export contacts: { section: "export_contacts", format: "vcf" }

Read WhatsApp call recordings made by the Kaption extension and their transcripts, with every word timed. Each recording names its conversation (the other person, or the group for a group call), so it links to query, get_contact and get_group. Recordings of locked chats are never returned.

Actions: list - Recordings, newest first (optional conversation_id, date_from, date_to, limit) get - One recording and its transcript: turns by speaker ("you" or "contact") with start/end seconds (requires id; include_words adds each word's timing) search - Recordings whose name or transcript matches the search text, with the matching lines (requires search; same filters as list)

Examples: Recent calls: { action: "list", limit: 10 } Calls with one person: { action: "list", conversation_id: "5491157390064@c.us" } Read a transcript: { action: "get", id: "1790000000000-a1b2c3d4" } What was said about the budget: { action: "search", search: "budget" }