chat-miner: parsers and artwork from your chat exports

Chat exports in, dataframes out

The project is described in one line in the README, that it provides lean parsers for every major platform transforming chats into dataframes, and that artistic visualizations let you explore the data and create artwork from your chats. The logo says it more plainly, chat-miner turns your chats into artwork. The important architectural decision is that the input is not a live account and not a database dump of messages, it is the export file that the messaging application itself produces. The README links the official export tutorials for WhatsApp, Signal, Telegram, Facebook Messenger and Instagram Chats, and the Signal link points at a third party export tool, which tells you that the format is not always something the vendor provides directly. That design has a consequence worth naming. The tool never talks to your account, never holds a session token and never scrapes the service, so there is nothing for it to break when a platform changes its interface, and equally nothing for it to fetch for you. You export, you point the parser at the file, and you get a table.

Five parsers with one shape

The parsing section shows the WhatsApp parser and says the usage of the Signal, Telegram JSON, Facebook Messenger and Instagram JSON parsers follows the same pattern, and that pattern is three lines.

from chatminer.chatparsers import WhatsAppParser

parser = WhatsAppParser(FILEPATH)
parser.parse_file()
df = parser.parsed_messages.get_df(as_pandas=True) # as_pandas=False returns polars dataframe

So each platform has a class, the class takes the path, parse_file does the work, and the parsed messages are then handed out as a dataframe. The choice of dataframe library is a parameter, and the default is the pandas interface, with as_pandas set to false returning a polars dataframe instead. That is a small design decision with a large convenience value, because a person who works in polars does not have to convert, and a person who works in pandas does not have to learn a new frame. The class names also tell you something about the inputs, since the Telegram and Instagram parsers are explicitly JSON parsers while the WhatsApp one is not, which follows from what those apps actually export.

Polars underneath, pandas at the edge

The dependency list in the packaging metadata explains the performance story, and it is short. The dataframe engine is polars with the pandas extra, so the package can hand you either representation, and the numeric work uses numpy, the charting uses matplotlib, the word cloud uses the wordcloud library, dates are handled with python-dateutil, progress bars with tqdm, and argparse is in the list even though the standard library has one. The build system is hatchling, the version is read dynamically out of the package init file, and the console script is registered as chatminer pointing at the CLI module. The classifiers describe the project as Production or Stable, with the intended audience as end users on the desktop and also science and research users. That combination is worth noticing, because the same library serves two rather different jobs. For a researcher, chat-miner is a way to get a tidy dataframe out of a chat export for analysis, and for a person with a folder of exports it is a way to get a poster for a wall. The lean framing in the README is aimed at the first use, and the visualisation module is what makes the second one possible without writing a single plotting line.

Four kinds of picture from the same dataframe

The visualisation module is a namespace of functions that take a dataframe and draw into a matplotlib axis, so the caller keeps control of the figure. The calendar heatmap draws a message count per day, one row per week, for a given year, and the README example stacks two years, one with a colour map and one with monthly borders.

import chatminer.visualizations as vis
import matplotlib.pyplot as plt

fig, ax = plt.subplots(2, 1, figsize=(9, 3))
ax[0] = vis.calendar_heatmap(df, year=2020, cmap='Oranges', ax=ax[0])
ax[1] = vis.calendar_heatmap(df, year=2021, linewidth=0, monthly_border=True, ax=ax[1])

The sunburst shows message count per daytime on a polar axis, with an option to highlight the maximum and a choice of isolines that can be absolute or relative, which is how you compare a small chat and a large one in the same style. The word cloud takes a stopword list and sizing parameters such as background colour, width, height and a maximum word count, and the radar chart shows message count per weekday. The radar one has a small wrinkle that will stop you if you skip it. It needs a factory registered before it will work, so you check is_radar_registered and, if it is not, call radar_factory with the number of sides and a frame style such as polygon.

if not vis.is_radar_registered():
	vis.radar_factory(7, frame="polygon")

The examples directory holds the rendered output as SVG for each of the four, which is a good way to see what the parameters do before you commit to a layout.

The CLI parses to CSV, and stops there

The command line interface is described in one sentence, that it supports parsing chat logs into csv files, and the next sentence is the limitation that matters, that as of now you cannot create visualizations from the CLI directly. The usage is a single line with a platform, an input and an output.

$ chatminer -p whatsapp -i exportfile.txt -o output.csv

The parser option accepts whatsapp, instagram, facebook, signal and telegram, the input is the file to be processed and the output is the file for the results, and the help text in the README is the full option list, which is short enough to memorise. So the division of labour is clear. The CLI is the batch stage, the one you point at a directory of exports from a cron job, and the Python API is the drawing stage, where you load a dataframe and compose a figure. If you want a picture from the command line, you write five lines of Python. That is a small gap, but it is the reason the project ships a library and not a tool, and it is worth knowing before you design a pipeline around it.

The Windows path trap, and the export step you cannot skip

There is one note in the parsing section that will save somebody an afternoon. Depending on the source system, Python requires converting the filepath to a raw string, and the README shows the two forms side by side, a Windows path with the drive letter and backslashes as a raw string, and a Unix path, with an assertion that the file exists.

import os
FILEPATH = r"C:\Users\Username\chat.txt" # Windows
FILEPATH = "/home/username/chat.txt" # Unix
assert os.path.isfile(FILEPATH)

The reason is the classic one, that a backslash before a letter that could be an escape sequence is interpreted, and the fix is the r prefix or a forward slash. The second point is the export step, and it is not optional. Section two of the README is entirely about exporting chat logs, and it points at the official tutorials for each platform, so the data acquisition is a manual action you perform in the app and then hand to the parser. The tool is downstream of that decision, which is a reasonable design for a project that must not hold your account credentials, and it is also a hard dependency on a process that is different for every platform and changes when the vendor changes their export screen.

Packaging, maintenance and the shape of the repository

The project is on PyPI under the name chat-miner, and the README gives the two install routes, the release from PyPI with its dependencies, and the source route for anyone who wants to run the latest code or build everything themselves, which is a clone, a directory change and a pip install of the checkout.

pip install chat-miner

git clone https://github.com/joweich/chat-miner.git
cd chat-miner
pip install .

The repository is small and well organised, with the chatminer package, a doc directory holding the static logo assets, an examples directory with the four rendered SVGs, a test directory, a codecov configuration, and a pyproject file that also configures coverage with the CLI, the visualisation module and the package init explicitly omitted from the coverage measurement. That last detail is a good sign about how the project thinks about its own quality, because the untested parts are exactly the two modules where a mistake is most visible to a user, the command line entry point and the drawing layer. The licence is MIT, the Python floor is 3.8, and the classifier list runs to 3.12. On maintenance, the last push was on 2026-10-16, but the newest release tag is v0.6.0 from 2025-01-04, with v0.5.4 in November 2024 and v0.5.3 in April 2024 before that, so the work continues on the branch while the published version moves in its own time.

Editorial conclusion

Adopt chat-miner if you already have exported chat logs and want a dataframe and a set of pictures from them without writing a regular expression per platform, because the per platform parsers are the part of the work that is tedious and easy to get wrong. It does not fit a pipeline that needs to run unattended against a live account, since the input is an export file and the project points you at the official export procedures for each platform, and it does not fit a script-only workflow, because the CLI stops at CSV. Before you build on it, read the exports section of the documentation for your platform and check the version you install, since the last release is v0.6.0 from 2025-01-04 while the repository is still receiving commits.

Frequently asked questions

Official sources

1. Issues
2. joweich/chat-miner on GitHub
3. License: MIT
4. README
5. Releases