Search WhatsApp
queryQuery 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" }
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Look up a specific conversation, contact, or label by ID | |
| list | No | Filter conversations by list name or ID (Personal accounts) | |
| after | No | Return messages after this ISO 8601 datetime (e.g. "2026-03-01T12:00:00.000Z") for incremental sync | |
| group | No | Filter contacts by group ID — only return contacts that are members of this group | |
| label | No | Filter conversations by label name or ID (Business accounts) | |
| limit | No | Max results (default 25, max 5000) | |
| query | No | Text to search for (names, messages, transcriptions) | |
| before | No | Return messages before this ISO 8601 datetime (e.g. "2026-03-01T12:00:00.000Z") for cursor-based pagination backward | |
| entity | No | Entity type to query. Defaults to "conversations" when listing, or all when searching. Use "session" to list all connected WhatsApp accounts. | |
| unread | No | Only return conversations with unread messages | |
| community | No | Filter conversations by community name or ID | |
| exclude_muted | No | Exclude muted conversations from listings (default false) | |
| target_session | No | Session ID to target a specific WhatsApp account. Get session IDs from entity="session". If omitted, routes to the most recently active account. | |
| exclude_archived | No | Exclude archived conversations from listings (default true) | |
| include_participants | No | Include group participants in results. Useful when looking up a contact by ID to see which groups they belong to, or when querying a group to see its members. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | No | The JSON-compatible result returned by the Kaption extension |