Skip to content
πŸ’¬πŸ“Š Fun data visualizations for Facebook Messenger chats
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


ChatStats is a data visualizer for a Facebook Messenger conversation. Try it out with your group chats or your significant other. You don't need to be an experienced programmer to use it!

Graph of our most distinguishing words

ChatStats also works with group chats!

Graph of most frequent emoji

More examples can be found in my blog post.


  • Average number of words per message
  • Days with the most messages
  • Each sender's most distinguishing words
  • Each term's most distinguishing words
  • Messages by hour of day
  • Messages by term
  • Messages by weekday
  • Most frequent stickers
  • Names said in chat
  • Number of messages sent

And more!

How To

Note: Not tested on Windows.


You will need the following installed:

  • Git
  • Python3
  • Pip3 (should be included when installing Python3)

Step One: Getting Your Facebook Data

To get your entire chat history:

  1. Go to Select "Download Your Information".
  2. On this page, change the Format option to JSON. You can deselect all information except for Messages to lower the size of your download. The other options can be left default or customized to your liking. Click Create File to continue.
  3. Facebook takes a few minutes to generate a download link for you. Once you receive a notification from Facebook with a download link, save the file to your computer and unzip it. You can do Step Two while waiting for the file to download.

Note that your Facebook data contains very sensitive information, so be careful storing it.

Step Two: Set Up ChatStats

  1. Clone or fork this repository:
git clone
  1. Install the dependencies:
pip3 install -r requirements.txt

Step Three: Generate Graphs!

  1. Go to your Facebook messages folder, and find the folder containing the chat you want to use.
  2. Use the path of that folder to run the following command:
python3 <chat_folder>

This creates a folder in chatstats/my_data/ with your ChatStats graphs.

Have fun! If you need help deciding what conversations to try, sort your messages folder by size. Try it out on all of your largest conversations!

Advanced Configuration

There are some advanced options available in the file


Feel free to request a feature or make a pull request. There are ideas for bug fixes, improvements, and new graphs in the project roadmap.

Getting Started With the Codebase

To create a new graph, create a new Grapher object in The file has many examples to help you get started.

ChatStats uses graphers in this code snippet from

# generate graphs that use message data
messages = clean_data(pd.DataFrame(json_data["messages"]))
for grapher in message_graphers:
    grapher.graph(messages, output_folder, parent_folder)

# generate graphs that use word data
words = word_data(messages)
for grapher in word_graphers:
    grapher.graph(words, output_folder, parent_folder)

Here we create two different dataframes, messages and words, which are called by graphers in corresponding message_graphers and word_graphers lists. For ChatStats to use a newly created grapher, it must be added to the appropriate list.

If your graph is complex enough that it needs a new dataframe, create it along with a corresponding list of graphers that use it.


Thanks to my girlfriend, Camille, for motivating me to build this tool so we could look through our chat history together.

I'd also like to thank /u/sumisel on Reddit. Their /r/dataisbeautiful post was the inspiration for this project.

You can’t perform that action at this time.