The Chat Export tool only exports messages that have already been synced to your TimelinesAI workspace. It cannot be used to retrieve or import WhatsApp conversations that occurred before connecting your number to TimelinesAI.
Note: Any custom export beyond the capability of the script can be requested as a paid service. Our Public API is available to create custom exports
The TimelinesAI Chat Export is an executable file that needs to be run locally on a Windows or macOS device.
Upon execution, it generates a collection of folders and files containing messages from WhatsApp chats synced into your TimelinesAI workspace. Once obtained, the executable file can be used an unlimited number of times (e.g., monthly or as needed).
Note: This process must be done by yourself, as the exported chat files are generated within your respective device.
How to get the executable files?
For Windows, download export-windows.exe
For macOS, download export-macos (after download, run
chmod +x export-macosin Terminal to mark it executable)
Both downloads always point at the most recent version of the tool. To check which version you are running, use the --version argument:
export.exe --version
All published versions, including release notes, are available at github.com/InitechSoftware/chat-history-export-releases/releases.
Get the API Key from TimelinesAI
Go to TimelinesAI
Then, click on "Public API" under the "Integrations" section
Within the "API Access Token", click on the "Generate token"
Lastly, copy by clicking on this button:
Important:
Do not regenerate the API key that you get while exporting chats. Otherwise, this operation may be affected and you may need to start over again.
For more information about the Public API feature, please click here.
Public API call quota
The Chat Export tool talks to TimelinesAI through the Public API. Each call to the Public API counts against your workspace's monthly API call quota, which is part of your subscription plan.
A typical export costs roughly:
One API call per page of chats — 50 chats per page, so approximately
total_chats / 50calls.One API call per non-empty chat to fetch its messages. Chats with no messages are detected from the chats listing and skipped without a separate call.
Additional calls for chats with very long histories (the tool requests messages 200 per page; chats with more than 200 messages take more than one call).
Before scanning any chats, the tool performs a pre-flight check and prints how many API calls you have left:
Workspace: acme-inc (plan: Business)
Public API monthly quota: 1234 / N used (N remaining; period ends 2025-02-01 00:00:00 +0000)
If the remaining quota is much smaller than your expected export size, you can decide to wait for the next billing period or contact support before proceeding. If the quota is already exhausted, the tool aborts immediately rather than burning through your time on calls that would all be rejected.
Where to see your quota inside TimelinesAI
Navigate to Integrations → Public API. The "TimelinesAI Credit & API Calls Usage" card on that page shows two lines:
Credit: N out of N messages left (used by message-sending features)
API Calls: N out of N calls left (used by every Public API call, including the export tool)
Plus a "Resets on the Nth of each month" line indicating when the quota refills.
If your export is going to exceed the available quota and you can't wait for the next billing cycle, contact [email protected] to request a quota increase.
API rate limits and how the tool handles them
In addition to the monthly quota, TimelinesAI rate-limits how many API calls you can make per minute. The Chat Export tool is built to stay within those limits automatically:
It paces itself at 30 requests per minute by default, comfortably under the standard limit. You normally do not need to change this.
If the server temporarily asks the tool to slow down, the tool waits the time the server requested (capped at 2 minutes), or — if the server doesn't specify — backs off with delays of 1, 2, 4, 8, 16 seconds.
After several failed retries in a row, the tool stops cleanly with a clear "Rate limit exhausted" message instead of looping silently. You can re-run the same command later (see "Resume" below) to pick up where it left off.
If your subscription plan includes a higher per-workspace API rate limit and you want the tool to use it, override the pacing with --rate_limit:
export.exe --api_token XXX --rate_limit 60
Setting --rate_limit 0 disables client-side pacing entirely (not recommended unless you know what you're doing).
Resume after an interruption
Long exports can take a while — sometimes hours, depending on the size of your workspace. If something goes wrong mid-export (you close the window, your computer goes to sleep, the network drops, the rate limit is reached, ...), you do not need to start from scratch.
To resume: just re-run the same command in the same folder. The tool will:
Detect which chats have already been exported in that folder (by looking at the
messages.xlsxfiles on disk).Skip those chats — no API call is made for them.
Re-fetch the one chat that was being processed when the previous run was interrupted (to make sure no messages are missed).
Continue with all the remaining chats.
No special flag is needed; this happens automatically. You'll see a line like this near the top of the output:
Resume detected: 345 chat(s) already exported on disk; will re-fetch chat 110269 (last in-flight) and continue with the rest.
To start fresh instead of resuming: simply delete (or rename, or move out of the way) the export folder before running again.
How to use the script on Windows:
Extract the obtained script into a folder in your local environment
Then, hover your cursor over the executable file and select "Copy as path"
Open the CMD or Command Prompt
Paste the executable file path
Add a space and then insert:
--api_token XXXand replace the X's with your API key from TimelinesAIAdd another space after the API key and insert the specific argument you'd like to work with (refer to the "Supported Arguments" list below)
Example:"C:\Users\{your_windows_user}\{folder}\export.exe" --api_token xxxxx-xxxx-xxxx-xxxx-xxxxxxxx --whatsapp_account +12345678910Press Enter/Intro and let the export begin
How to use the script on macOS:
Extract the obtained script
In the OS settings, enable the option to "Run applications from unidentified developers."
Preferably, place the extracted file in the root of the user folder
Open the Terminal
Run the command:
/Users/{your_mac_user}/{folder}/export --api_token xxxAdd another space after your API key and insert any of the specific arguments you'd like to work with (refer to the "Supported Arguments" list below)
Supported Arguments:
To download attachments:
--download_attachments
Example:export.exe --api_token XXX --download_attachments
To export messages after a specified date (format: YYYY-MM-DD):
--start_date {your_date}
Example:export.exe --api_token XXX --start_date 2026-02-17
To export messages before a specified date (format: YYYY-MM-DD):
--end_date {your_date}
Example:export.exe --api_token XXX --end_date 2026-02-17
To export messages from a specific WhatsApp account phone number that you have connected to TimelinesAI:
--whatsapp_account {+12345678910}
Example:export.exe --api_token XXX --whatsapp_account +972501111111
To export only specific chats by their IDs (space-separated):
--chat_id {ID1} {ID2} ...
Example:export.exe --api_token XXX --chat_id 12345 67890
To pace the tool at a custom rate (default 30 calls/minute):
--rate_limit {N}
Example:export.exe --api_token XXX --rate_limit 60
To request larger pages of messages per call (default 200; lower if responses time out):
--messages_page_size {N}
Example:export.exe --api_token XXX --messages_page_size 100
To check which version of the tool you are running:
--version
Example:export.exe --version
To show a help message with the supported arguments:
-h
Example:export.exe --api_token XXX -h
Once the script execution is initiated, you will see the following output:
First, the tool prints its version, the workspace identity, and the current Public API quota:
TimelinesAI Chat Export Tool vX.Y.Z
Workspace: acme-inc (plan: Business)
Public API monthly quota: 1234 / N used (N remaining; period ends ...)
If you are resuming a previous run, you'll also see a "Resume detected" line.
Then, for each chat that gets processed, the tool prints a per-chat summary line:
Chat ID: XXX, Chat Name: YYYY, Messages Exported: ZZZ, Attachments Downloaded: ZZZ, API Errors: 0
Once the whole operation is done, it ends with:
Export Completed!
Number of API requests made: X
Total running time: X seconds
Total number of WA accounts exported: X
Total number of Chats exported: X
Empty chats skipped (no messages): X
Chats skipped on resume (already on disk): X
Total number of Messages exported: X
Total number of attachments downloaded: X
Total size of attachments downloaded: X.XX MB
Note: Execution time depends on the number of chats/messages in your workspace. It might take from several minutes to several hours.
If something goes wrong, the tool prints "Export FAILED" instead of "Export Completed!" plus a short reason on the last line, and exits with a non-zero exit code. See export_log.log in the same folder for full details. You can re-run the same command in the same folder to resume — see "Resume after an interruption" above.
Execution results
Open the folder with the script
When the script has been successfully executed, it will contain folder(s) with chat exports. If you have multiple WhatsApp accounts and have executed an export for several of them, each WhatsApp account will be represented by its own folder:
Open the desired folder
Each folder will have an overview Excel spreadsheet and subfolders:
Overview Excel Spreadsheet will contain the list of chats and their Chat IDs with the following additional chat information:
Subfolders represent a single chat and are named after the corresponding chat ID. Each subfolder, in turn, will have an Excel file with all the messages from the particular chat ID. This Excel file will contain the following information:
