<commit_before># Facebook Chat Archive Parser [![Build Status](https://travis-ci.org/ownaginatious/fbchat-archive-parser.svg?branch=master)](https://travis-ci.org/ownaginatious/fbchat-archive-parser)
A small tool and library for parsing chat history from a Facebook data archive into more usable formats.

## What is a "Facebook Chat Archive"?

Facebook Messenger records all your conversation history since the beginning of time. If you want it back for some reason, you have two options:

1. Create a scraper that constantly "scrolls up" in the conversation window you're interested in (or simulates that with API calls), progressively getting more and more of your chat history.

2. Ask Facebook for an archive of *all* your data [here](https://www.facebook.com/dyi) , and wait a couple of days for them to give it to you as a zip archive.

Number 2 is the only practical option if you want *everything* in a timely manner.

### What does Facebook give me in this zip archive?

Facebook gives you literally everything you've ever posted to Facebook, which includes your pictures, videos, posts. etc in addition to your chat messages.

Your chat history comes in a single HTML page titled `messages.htm`. Unfortunately, the data is mostly unordered and impossible to load into your web browser (it can be several hundred megabytes in size). You're essentially forced to parse it if you want to analyze the content.

### Why would I ever want my Facebook chat history?

There are a number of reasons you may want to parse your Facebook chat history:

1. To make a simulation of your friends using [Markhov chains](https://en.wikipedia.org/wiki/Markov_chain).
2. You're deleting your Facebook account, but would like a record of your conversations.
3. You need to analyze a copy of your conversations for legal reasons.

## Here comes the Facebook Chat Archive Parser!

The Facebook Chat Archive Parser is a command line tool (and library for advanced users) for easily transforming your `messages.htm` file into something actually useful.

### How do I get it?
Install the Facebook Chat Archive Parser via `pip` under at least Python 2.7:
```bash
pip install facebook-chat-archive-parser
```

### How does it work?
Simply run the command `fbcap` in your terminal with your `messages.htm` file as the argument.

```bash
fbcap ./messages.htm
```

And watch as the parser sifts through your data!

![Processing gif](https://zippy.gfycat.com/VariableAlarmedGander.gif)

When it's done, it will dump all your conversation history is dumped to `stdout`. Obviously, this can be very long, so here is an example:

![Results](http://imgur.com/pXnGJFs.png)

### What if I want JSON?

Simply supply the `-f json` option to the command line:

```bash
fbcap ./messages.htm -f json
```

The output format is as follows:

```json
{
    "threads": [
    	{
            "participants": ["participant_0", "...", "participant_n"],
            "messages": [ // Ordered from oldest to newest
                {
                    "date": "ISO 8601 formatted date",
                    "sender": "sender name",
                    "message": "message text"
                },
                "..."
            ]
        },
        "..."
    ]
}
```

### How about CSV?

Of course!

```bash
fbcap ./messages.htm -f csv
```

### What if I want to see some statistics?

See who you talk to the most among your friends and how much each of you contribute to the conversation.

```bash
fbcap ./messages.htm -f stats
```
![stats image](http://www.ultraimg.com/images/ScreenShot2016-01-25at1.27.57PM.png)

### How do I get any of the above into a file?

Just use standard file redirects.

```bash
fbcap ./messages.html > my_file.txt
```

### What if I only want to parse out a specific conversation?

You can use the `-t` option to specify a particular conversation/thread you want to output. Just provide a comma-separated set of names. If you don't remember a last name (or conversely, only remember the last name), the system will try to compensate.

```bash
fbcap ./messages.html -t second
```
![filter second](http://www.ultraimg.com/images/ScreenShot2016-01-25at1.43.25PM.png)

```bash
fbcap ./messages.html -t second,third
```
![filter second and third](http://www.ultraimg.com/images/ScreenShot2016-01-25at1.43.33PM.png)

# What else can I do?
```
$ fbcap --help
fbcap: A program for converting Facebook chat history to a number of more usable formats

Usage: fbcap {{arguments}} {{options}}

Arguments:
  path [text]  Path of the messages.htm file to parse

Options:
  -h, --help           Show this help message and exit
  -f, --format [str]   Format to convert to (json, csv, text, stats) (default: text)
  -t, --thread [text]  Only include threads involving exactly the following comma-separated participants in output (-t 'Billy,<NAME>)<commit_msg>Fixed broken JSON render<commit_after># Facebook Chat Archive Parser [![Build Status](https://travis-ci.org/ownaginatious/fbchat-archive-parser.svg?branch=master)](https://travis-ci.org/ownaginatious/fbchat-archive-parser)
A small tool and library for parsing chat history from a Facebook data archive into more usable formats.

## What is a "Facebook Chat Archive"?

Facebook Messenger records all your conversation history since the beginning of time. If you want it back for some reason, you have two options:

1. Create a scraper that constantly "scrolls up" in the conversation window you're interested in (or simulates that with API calls), progressively getting more and more of your chat history.

2. Ask Facebook for an archive of *all* your data [here](https://www.facebook.com/dyi) , and wait a couple of days for them to give it to you as a zip archive.

Number 2 is the only practical option if you want *everything* in a timely manner.

### What does Facebook give me in this zip archive?

Facebook gives you literally everything you've ever posted to Facebook, which includes your pictures, videos, posts. etc in addition to your chat messages.

Your chat history comes in a single HTML page titled `messages.htm`. Unfortunately, the data is mostly unordered and impossible to load into your web browser (it can be several hundred megabytes in size). You're essentially forced to parse it if you want to analyze the content.

### Why would I ever want my Facebook chat history?

There are a number of reasons you may want to parse your Facebook chat history:

1. To make a simulation of your friends using [Markhov chains](https://en.wikipedia.org/wiki/Markov_chain).
2. You're deleting your Facebook account, but would like a record of your conversations.
3. You need to analyze a copy of your conversations for legal reasons.

## Here comes the Facebook Chat Archive Parser!

The Facebook Chat Archive Parser is a command line tool (and library for advanced users) for easily transforming your `messages.htm` file into something actually useful.

### How do I get it?
Install the Facebook Chat Archive Parser via `pip` under at least Python 2.7:
```bash
pip install facebook-chat-archive-parser
```

### How does it work?
Simply run the command `fbcap` in your terminal with your `messages.htm` file as the argument.

```bash
fbcap ./messages.htm
```

And watch as the parser sifts through your data!

![Processing gif](https://zippy.gfycat.com/VariableAlarmedGander.gif)

When it's done, it will dump all your conversation history is dumped to `stdout`. Obviously, this can be very long, so here is an example:

![Results](http://imgur.com/pXnGJFs.png)

### What if I want JSON?

Simply supply the `-f json` option to the command line:

```bash
fbcap ./messages.htm -f json
```

The output format is as follows:

  > Messages are ordered from oldest to newest.
   
```json
{
    "threads": [
    	{
            "participants": ["participant_0", "...", "participant_n"],
            "messages": [
                {
                    "date": "ISO 8601 formatted date",
                    "sender": "sender name",
                    "message": "message text"
                },
                "..."
            ]
        },
        "..."
    ]
}
```

### How about CSV?

Of course!

```bash
fbcap ./messages.htm -f csv
```

### What if I want to see some statistics?

See who you talk to the most among your friends and how much each of you contribute to the conversation.

```bash
fbcap ./messages.htm -f stats
```
![stats image](http://www.ultraimg.com/images/ScreenShot2016-01-25at1.27.57PM.png)

### How do I get any of the above into a file?

Just use standard file redirects.

```bash
fbcap ./messages.html > my_file.txt
```

### What if I only want to parse out a specific conversation?

You can use the `-t` option to specify a particular conversation/thread you want to output. Just provide a comma-separated set of names. If you don't remember a last name (or conversely, only remember the last name), the system will try to compensate.

```bash
fbcap ./messages.html -t second
```
![filter second](http://www.ultraimg.com/images/ScreenShot2016-01-25at1.43.25PM.png)

```bash
fbcap ./messages.html -t second,third
```
![filter second and third](http://www.ultraimg.com/images/ScreenShot2016-01-25at1.43.33PM.png)

# What else can I do?

Take a look at the help options to find out more!

```
$ fbcap --help
fbcap: A program for converting Facebook chat history to a number of more usable formats

Usage: fbcap {{arguments}} {{options}}

Arguments:
  path [text]  Path of the messages.htm file to parse

Options:
  -h, --help           Show this help message and exit
  -f, --format [str]   Format to convert to (json, csv, text, stats) (default: text)
  -t, --thread [text]  Only include threads involving exactly the following comma-separated participants in output (-t 'Billy,<NAME>)
{'fraction_non_alphanumeric': 0.09632745178498153, 'fraction_numerical': 0.010668855149774312, 'mean_word_length': 3.492626728110599, 'pattern_counts': {'":': 12, '<': 5, '<?xml version=': 0, '>': 8, 'https://': 10, 'lorem ipsum': 0, 'www.': 8, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 30, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5337224', 'n_tokens_mistral': 2876, 'n_tokens_neox': 2650, 'n_words': 1289}