About whatstk

whatstk is a python package providing tools to parse, analyze and visualize WhatsApp chats developed under the sociepy project. Easily convert your chats to csv or simply visualize statistics using the python library. The package uses pandas to process the data and plotly to visualise it.

You can also try a live demo.

The project is distributed under the GPL-3.0 license and is available on GitHub.

First contact with whatstk

whatstk is built around BaseChat object interface, which requires class method from_source to be implemented. This method loads and parses the source chat file into a pandas.DataFrame.

Below, we use method df_from_txt_whatsapp to load LOREM chat. To test it with your own chat, simply export it as a txt file to your computer and then use class argument filepath, as shown in the following example.

>>> from whatstk import df_from_txt_whatsapp
>>> from whatstk.data import whatsapp_urls
>>> df = df_from_txt_whatsapp(filepath=whatsapp_urls.LOREM)
>>> df.head(5)
                 date        username                                            message
0 2020-01-15 02:22:56            Mary                     Nostrud exercitation magna id.
1 2020-01-15 03:33:01            Mary     Non elit irure irure pariatur exercitation. 🇩🇰
2 2020-01-15 04:18:42  +1 123 456 789  Exercitation esse lorem reprehenderit ut ex ve...
3 2020-01-15 06:05:14        Giuseppe  Aliquip dolor reprehenderit voluptate dolore e...
4 2020-01-15 06:56:00            Mary              Ullamco duis et commodo exercitation.

Installation & compatibility

This project is on PyPI, install it with pip:

pip install whatstk

Project has been tested in Python>=3.7.

From source

Clone the project from the official repository and install it locally

git clone https://github.com/lucasrodes/whatstk.git
cd whatstk
pip install .


To use Google Drive or Chat Generation support, install the library along with the corresponding extensions:

pip install whatstk[gdrive]
pip install whatstk[generate]

Or install the full suite:

pip install whatstk[full]


You can also install the version in development directly from github develop branch.

pip install git+https://github.com/lucasrodes/whatstk.git@develop

Note: It requires git to be installed.


You can ask questions and join the development discussion on Gitter. Use the GitHub issues section to report bugs or request features. You can also check the project roadmap.

For more details, refer to the contribute section.

Why this name, whatstk?

whatstk stands for “WhatsApp Toolkit”, since the project was initially conceived as a python library to read and process WhatsApp chats.