Request on-demand history for a chat

Requests from WhatsApp an on-demand sync of older messages from a chat, going backward from a reference message (anchor).

To recover a saved message that failed to open (messageType: "error" in /message/find), use POST /message/reload.

Rules:

• send number
• count is optional and limited to 100
• messageid is optional; when provided, the API uses that message as the reference to fetch older messages from the chat

Note:

• Important: recovery may only happen after opening WhatsApp on the phone or keeping it active in the background
• messageid defines the reference message for loading earlier history; this field does not fetch that specific message
• if you want to recover only a specific message X via history, provide as messageid the message right after X and use count=1
• if messageid is not provided, the API uses the oldest locally known message of that chat as the reference to fetch earlier history
• messages are returned later via webhook/SSE in history type events and are also available in /message/find

Result

The response contains the request’s request_id. Messages arrive in the history webhook/SSE with event: "messages" and the request_id in each message. It also appears at the top of messages and chats batches when the entire batch belongs to the same request; mixed batches may omit it at the top. The request ends with a single event: "status" batch with the same request_id:

• status: completed when WhatsApp confirms the request’s completion, timeout when there was no conclusive response within 2 minutes, blocked when the phone indicates more messages but did not deliver a page that advances
• success and error: only when there is no possible next page; success: false and the reason in error (pagination_no_progress, anchor_unavailable, history_access_unavailable or cursor_lookup_failed). Always come with blocked
• has_more: what the phone declared. true there are more messages on the phone, false the beginning of the conversation was reached, null not confirmed. Some devices declare true in every on-demand response, including empty ones: with them, pagination ends in blocked with pagination_no_progress, never in has_more: false
• history_access: unavailable when there are more messages but WhatsApp does not grant access to them
• next_request: ready-made body to request the earlier messages; resend it as received. null when there is no usable next request

To paginate, resend next_request from the final result until it comes back null, waiting for the result of each request. completed ends the request, not the whole conversation. next_request: null without has_more: false does not prove the beginning of the conversation. Silence or a batch with fewer messages than count does not indicate the end of the history: only has_more: false does.

With blocked and error: "pagination_no_progress", stop paginating that chat without automatically repeating the request: it is the end of what the phone delivers from that anchor, and repeating gives the same result.

Each chat has one active request at a time. Repeating the request with the same reference message before the status returns the same request_id (details.reused: true), without a new send to the phone. A request with a different reference ends the previous one, which receives its own final status (usually timeout), and proceeds normally. 409 only occurs when the provided requestId is already in use.

The final result arrives via webhook/SSE within 2 minutes after sending the request to WhatsApp (details.result_timeout_ms). Late messages may keep arriving with the same request_id for about 5 minutes after the request, without a second final status.

Synchronous mode (sync: true)

sync: true holds the response until the result, for up to timeoutMs (default and maximum 25000). Messages come in messages, and the top of the response contains the same fields as the final status (status, has_more, history_access, received_messages, next_request), plus received, timed_out and partial:

• final result within the deadline: 200 with that result;
• messages arrived, but not the result: 200 with status: "pending", about 2 seconds after the last message;
• nothing arrived within the deadline: 202 with status: "pending", timed_out: true and empty messages.

With status: "pending", the final result arrives later via the history webhook/SSE, with the same request_id. The webhook and SSE are also sent in synchronous mode, and messages are saved the same way.

Deleted reference message

If the anchor was deleted, the API tries to use the next valid message of that chat. details.requested_anchor_messageid reports the requested reference, details.anchor_messageid the one used, and details.anchor_replaced indicates the substitution. With no alternative, it returns HTTP 400 with status: "anchor_unavailable"; try without messageid to use the oldest saved message.