`wacli` primarily synchronizes new messages and updates as they occur. However, to retrieve older message history for a specific chat, `wacli` provides a "backfill" mechanism that requests older messa
wacli primarily synchronizes new messages and updates as they occur. However, to retrieve older message history for a specific chat, wacli provides a "backfill" mechanism that requests older messages from your primary WhatsApp device (your phone). This process is known as on-demand history synchronization.
wacli history backfill CommandThe history backfill command allows you to initiate these requests for older messages for a specific chat.
Purpose: To fetch messages that predate your wacli session or were not captured during initial syncs, by requesting them from your primary WhatsApp device.
wacli communicates with your phone to retrieve this older history.wacli uses the timestamp and ID of the oldest locally stored message in the specified chat as the anchor point for its requests. It tells your primary device, "give me messages older than this one."--count: It is recommended to use --count 50 per request. Requesting too many messages at once might lead to timeouts or incomplete responses from WhatsApp.The wacli history backfill command comes with several important options:
--chat <JID>: (Required) Specifies the JID of the chat you want to backfill. This can be a direct message JID (e.g., [email protected]) or a group JID (e.g., [email protected]).--count <N>: Determines the maximum number of messages to request in each individual on-demand sync request. The recommended value is 50. Setting it too high might cause requests to fail. Defaults to 50.--requests <N>: Specifies how many consecutive on-demand requests wacli should attempt. Each request will try to fetch older messages based on the current oldest message in your local database. wacli will stop if no older messages are returned, if it reaches the beginning of the chat's history, or if the specified number of requests is met. Defaults to 1.--wait <duration>: Sets the maximum time wacli will wait for a response from WhatsApp after sending an on-demand history sync request. If a response isn't received within this duration, the request is considered timed out. Defaults to 60s.--idle-exit <duration>: After all backfill requests have been sent, wacli will continue to listen for incoming messages and history responses for this duration. If no events are received within this idle period, wacli will exit. This ensures that any delayed responses for the backfill requests are still captured. Defaults to 5s.To backfill history for a specific chat (e.g., [email protected]), attempting 10 requests, each asking for 50 messages:
You can automate the backfill process for all chats already known in your local wacli database using a script. This example uses jq for JSON parsing, so ensure it's installed on your system.
How the script works:
pnpm -s wacli -- --json chats list --limit 100000: This command lists all chats known to wacli (up to 100,000) and outputs them in JSON format (--json). The -- is used to separate pnpm's arguments from wacli's arguments.| jq -r '.[].JID': The JSON output is piped to jq, which extracts just the JID field from each chat object. The -r flag ensures raw string output without JSON quotes.| while read -r jid; do ... done: The extracted JIDs are then piped, one by one, into a while loop.pnpm -s wacli -- history backfill --chat "$jid" --requests 3 --count 50: Inside the loop, for each jid, the history backfill command is executed. It attempts to backfill 3 requests, each asking for 50 messages, for the current chat JID.This script provides a powerful way to ensure your local wacli database is as complete as possible across all your conversations.
For more information on wacli and other commands, refer to the [Getting Started] page.