Kaption WhatsApp

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" }

Create a one-time attachment upload slot, authorized by your connected Kaption account (attachments from an assistant must be turned on for it). Returns uploadUrl, attachmentRef and expiresAt. PUT the raw file bytes to uploadUrl within 15 minutes (e.g. curl -T file.pdf), then pass attachment: {ref: attachmentRef} to send_message, a local schedule create/update, or manage_status schedule (photo or video status) within one hour. The extension consumes the ref once and stores the bytes locally. No third-party URLs. Needs a newer Kaption version; target_session selects the account.

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" }

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

section="overview" (default) is a compact summary; the other sections give detail.

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" }

Get one custom chat list and the chats in it, by ID or name.

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" }

Read the note saved for a contact. Requires a WhatsApp Business account with notes enabled.

Fetch a single group with a live participant list: membership is refreshed from WhatsApp before reading, so it includes recent joins and leaves. list_groups lists every group from the cache instead.

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

Get one personal Kaption reminder by its ID (from list_reminders).

Get one scheduled WhatsApp message by its ID (from list_scheduled_messages or send_message). Pass mode "local" for a message sent from this computer.

List the personal account's custom chat lists (e.g. "Family", "Work") with their chat counts, and whether lists are enabled on this account.

List WhatsApp contacts from the encrypted local 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 }

List all WhatsApp groups the user belongs to. Reads from the cache — no network. get_group returns one group with its membership fetched live from WhatsApp.

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

List the user's personal Kaption reminders (title, time, how they notify, completed or not).

Examples: Active reminders: {} Everything: { filter: "all" }

List scheduled WhatsApp messages of both modes; each item says its mode: bot - sent from Kaption's WhatsApp number, stored in Kaption's cloud local - "From this computer": sent from the user's own WhatsApp number while this computer and WhatsApp are open

Examples: Waiting to be sent: {} Only local ones, any state: { mode: "local", filter: "all" }

List the user's scheduled WhatsApp Status posts (id, type, state, time, text or caption) and, when WhatsApp has them loaded, the statuses the user posted recently. Changes nothing.

Examples: Waiting to be posted: {} Everything: { filter: "all" }

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

Create, edit or delete personal chat lists (custom lists), and add or remove their chats. These are the personal account equivalent of Business labels. Lists organize chats into custom categories like "Family", "Work", etc. Not every account has lists; list_chat_lists says whether they are enabled. Reading lists is list_chat_lists and get_chat_list.

Actions: 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: Create: { action: "create", name: "Family", conversation_id: ["number@c.us"] } Add chat: { action: "add_chat", name: "Family", conversation_id: "number@c.us" }

Write or replace the note for a contact. Requires a WhatsApp Business account with notes enabled. Reading a note is get_contact_note.

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

Create, change, complete or delete personal reminders. Reminders are stored in the cloud and trigger notifications via the Kaption extension. Reading reminders is list_reminders and get_reminder.

Actions: 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: Create: { action: "create", title: "Follow up with client", datetime: "2026-03-07T14:00:00Z" } Complete: { action: "complete", id: "rem_abc123" }

Schedule, change or cancel WhatsApp messages 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). Supports one image, document, audio or video attachment (8 MiB max), when attachments from an assistant are turned on for the account and Kaption is up to date; audio captions are refused. 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)".

Reading scheduled messages is list_scheduled_messages and get_scheduled_message.

Actions: 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: 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" }

Schedule a post to the user's WhatsApp Status (stories) for a future date and time, or cancel a scheduled status post. The post is made later by the user's own WhatsApp on this computer; to post right now the user uses WhatsApp itself, so there is no post-now action. Only when status posts are turned on for the account; needs the "From this computer" scheduled mode and its consent in Kaption (an assistant cannot accept consent). A status is either text (max 700 characters) on a background colour (#RRGGBB) with a font (0-7), or one image (JPG/PNG/WebP) or MP4 video with an optional caption (max 1024). Images and videos need create_attachment_upload: call it with the file's name, mime and size, PUT the raw file bytes to its uploadUrl, then call manage_status schedule with attachment: { ref: attachmentRef } (one use, within an hour). The inline attachment { name, mime, dataB64 } is still accepted. Who sees it follows the user's WhatsApp status privacy setting. WhatsApp must be open on this computer at posting time: the Kaption bot and cloud templates cannot post statuses. datetime must be in the future. Each post counts as one scheduled item in the plan's scheduling quota, and the mode's limits (per hour, per day, pending) still apply; scheduling is not a delivery confirmation.

Reading status posts is list_status_posts.

Actions: schedule: { action: "schedule", datetime: "2026-10-27T09:00:00-03:00", text: "Open today 9-18", background_color: "#25D366", font: 2 } schedule (photo/video): create_attachment_upload { name: "menu.jpg", mime: "image/jpeg", size: 245760 }, PUT the bytes to its uploadUrl, then { action: "schedule", datetime: "2026-10-27T09:00:00-03:00", attachment: { ref: "" }, caption: "New menu" } cancel: { action: "cancel", id: "" }

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

Several WhatsApp accounts may be connected (e.g. personal + business), each with its own conversations, contacts and messages. entity="session" lists the connected accounts and their session IDs; target_session routes a query to one of them.

Reading messages: Passing a conversation id (e.g. "5491157390064@c.us") returns the conversation with its messages; limit sets how many. entity="messages" is a global text search across conversations.

Audio transcriptions: entity="transcriptions" (with an optional query) returns voice-note transcriptions; messages read by conversation id include the transcription text of audio messages.

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" }

Queue a WhatsApp message from this computer for the earliest permitted delivery. Needs a newer Kaption version, sending from this computer turned on for the account, and the user's consent in Kaption. Supports an existing person chat or eligible group (@g.us) and one image, document, audio or video attachment (8 MiB max). Message is optional with an attachment; audio cannot have captions. Returns queued plus a schedule ID, not proof of delivery. Existing ask-first prompts, 8/hour, 20/day, group limits and delays apply. An assistant cannot accept consent or confirmation. Computer and WhatsApp must remain open. The returned ID can be read with get_scheduled_message (mode local) and cancelled with manage_scheduled_messages (mode local).

Get or generate a summary of a conversation