get_whatsapp_chat_messages
Retrieve WhatsApp chat messages (both inbound and outbound) for a specific device. Backed by the device-scoped Chat Messages endpoint, which requires a Platform subscription on the target device.
Available actions:
recent: Latest messages in a chat (newest first by default)
search: Text search across messages (within a chat or device-wide)
date_range: Messages in a specific time window
by_sender: Messages sent from a specific phone number or WID
by_type: Messages filtered by type (text, image, video, audio, document, location, contact, etc.)
by_id: Fetch a specific message by its WhatsApp message ID
thread: Get conversation context around a specific message (N before + target + N after)
media: Messages containing media files
The 'device' parameter accepts a device ID (24-hex), phone number in E.164 format, or device alias (e.g., "Sales 2") — pass exactly what the user named in their request. If the account has a single device, omit it and it will be auto-selected. If the account has multiple devices and the user didn't name one, the tool returns an error listing available devices — ask the user which one they mean.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| chat | No | WhatsApp chat ID. Required for all actions except by_id and search (which accepts device-wide search when chat is omitted) | |
| limit | No | Maximum messages to retrieve per request (REST API caps at 50) | |
| query | No | Text to search for (required for search action) | |
| action | Yes | Action to perform for WhatsApp message retrieval operations | |
| device | No | Target WhatsApp device — accepts device ID (24-hex), phone number in E.164 format, or device alias. Optional: if the account has a single device, it is auto-selected; otherwise specify which one. | |
| fields | No | Explicit dot-path allowlist, e.g. ['id','date','flow','body']. Overrides verbosity when set. | |
| sender | No | Phone number or WID of message sender (required for by_sender action) | |
| toDate | No | Upper bound of the date range (maps to REST `before`) | |
| fromDate | No | Lower bound of the date range (maps to REST `after`) | |
| messageId | No | Specific message ID (required for by_id and thread actions) | |
| sortOrder | No | Sort order by date (default: desc) | |
| verbosity | No | Response detail level: summary = curated high-signal fields (default, token-lean); standard = broader set; full = complete message objects (escape hatch). | summary |
| mediaTypes | No | Filter by specific media types (media action) | |
| contextAfter | No | Messages after target message (thread action) | |
| includeMedia | No | Reserved for compatibility — media is always included when present | |
| messageTypes | No | Types of messages to retrieve (required for by_type action) | |
| contextBefore | No | Messages before target message (thread action) | |
| includeQuotes | No | When true, request quoted message details from the API (off by default to keep responses lean) | |
| includeReactions | No | Reserved for compatibility — reactions are returned inline by the REST API when available | |
| includeFileDetails | No | Return full media file metadata (media action) |