Measure a chat's earlier history
start_history_previewMeasure how much earlier history a WhatsApp chat has — before or after it is captured — and get the options to capture it. Measuring is free and reads metadata only, but takes minutes: the first call starts it and answers measuring; call again in 1–3 minutes to read progress, never in a loop. Once a day is counted in full, options appear, each with how many messages, media, bytes and voice-note minutes it brings and its price; all history is on offer once the status is ready. Pass from_date to also get one exact day. A stopped, canceled, failed or unanswered measure stays as it is: continue or retry it only when the user asks, with continue: true. Pass a list of up to 100 chat_ids for a metadata-only batch of chats not captured yet. Name the chat with chat_id, contact_phone or chat_name from list_capturable_chats; phone may be omitted when the user has a single number. If this tool answers an error whose code is currency_selection_required, the user has not confirmed the account's currency: show them the action_url and do not retry until they say it is done.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "start_history_preview"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| phone | No | The connected number, from list_connected_numbers. Omit it when the user has a single connected number. | |
| chat_id | No | The chat, by the chat_id list_capturable_chats returns, or a list of 1–100 of them for a batch. Pass exactly one of chat_id, contact_phone and chat_name. | |
| continue | No | Continue a stopped measure, or retry a failed or unanswered one. Only when the user asks; default false. | |
| chat_name | No | The chat, by its name exactly as list_capturable_chats returns it. Pass exactly one of chat_id, contact_phone and chat_name. | |
| from_date | No | Optional YYYY-MM-DD: also answer the option starting on this day. | |
| contact_phone | No | The chat, when it is a 1:1: the other party's number in E.164. Pass exactly one of chat_id, contact_phone and chat_name. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | queued | measuring | stopped | not_measured | phone_unanswered | failed | nothing_earlier | ready | limit_reached | captured | |
| options | No | ||
| results | No | Batch only: one per distinct chat_id, in input order, metadata only. | |
| currency | No | The currency of every price below. | |
| help_url | No | How earlier history and its cost work, for the user. Only for a captured chat. | |
| next_step | No | What to tell the user, and do, for this status. | |
| estimate_id | No | When the chat is not captured: its measure. | |
| measured_at | No | Ready: when the measure finished (ISO 8601). | |
| current_from | No | When the chat is captured: the local day its capture starts from. | |
| messages_seen | No | Messages examined so far while measuring; not messages captured. | |
| available_from | No | Ready: the earliest day WhatsApp served. | |
| estimates_used | No | ||
| failure_reason | No | request_failed | phone_unanswered. | |
| conversation_id | No | When the chat is captured: the conversation the read tools take. | |
| counted_back_to | No | Before ready: the earliest local day counted in full; no option goes earlier. | |
| reached_back_to | No | Earliest local day examined so far. | |
| available_through | No | Ready: the newest day measured. | |
| estimates_remaining | No | Remaining measure allowance; null when measures are not limited. | |
| estimate_queue_position | No | 1-based position while queued. | |
| included_in_subscription | No | True when this number's subscription covers the history: nothing is charged. |