How to export and backup your Google Hangouts chat history

2014-11-10 / Jay2k1 / 426 Comments

TL;DR: I’ve written a web tool you can use to view and download your Hangouts chat history. Click this link and follow the instructions.

Google Hangouts as messaging platform has some advantages over other often used services. On my smartphone, I mainly use WhatsApp and Threema, but ~~both lack other clients so far~~ WhatsApp web can only be used from one device at a time, and Threema lacks a web/desktop client, so communication is limited to using the smartphone which is somewhat annoying for longer conversations. This is a thing I like about Hangouts, it happens on all my devices and I can hop in and out of a conversation wherever I am at that time.

The problem

However, a major downside for me is the inability to export your chat. Sometimes you want to re-read some conversation you’ve had, or search for something the chat partner has said, like a link to a website. Now I am used to using IRC (Internet Relay Chat), which is kind of oldschool but – depending on the chat client configuration – can log everything to text files. You can read them, grep them, search for links, nicknames, everything. Log files of conversations are great.

Since I do not have Gmail, I can’t tell how accessible or not the chat history is in the Gmail web interface, but in the Chrome app, Android app and the chat box on the Google+ website, you can only see the last 50 or so messages. If you scroll up more than that, it dynamically loads more messages from the server. Then again, scroll up, and it will load some more. If you had a couple of long conversations, this can take quite a while, and even when you do this, the output produced by selecting all and copy pasting the chat to a text editor is ugly and not useful. So I googled how to export the chat. WhatsApp for example lets you send conversation histories via e-mail, which is great. It seems, however, that Hangouts cannot do this – there is no export/archive function whatsoever.

Getting closer

Yet there is a way to access that data, it’s just not as trivial as clicking an “export to .txt” button. One of Google’s several tools, Google Takeout, allows you to download all your Google account related data, i.e. your g-mails, calendar data, contacts, Google+ posts… and Hangouts conversations. When you do this, it will create a .zip archive containing a file which contains the chat data, JSON encoded.

Google Hangouts Takeout JSON — What Hangouts.json looks like

This file is full of unnecessary rubbish, I estimate less than 10% of the file contents are actual chat messages, the rest is metadata such as participant IDs, conversation IDs, read status, timestamps, and lots of other things. This makes the file unreadable and messy (note that there is not even one actual chat message in the part I screencaptured).

My Solution

I spent some time analyzing the structure of that JSON and wrote a parser in PHP to turn the JSON into different useful formats. It offers the following views and download options:

HTML view, displays the chat nicely formatted in a messenger-like style so you can easily read through it (features clickable links, embedded images etc.)
Text view, shows the chat in an IRC-like format that you could copy paste to a text editor.
XML view, in a textbox, to be copy-pasted somewhere.
XLSX download, all conversations in a single Excel 2007 (Office Open XML) document
CSV download, this can be opened in Excel, LibreOffice Calc etc.
ZIP with CSVs, all conversations as single CSV files, bundled in a .zip archive to download

In order to use the parser, you have to…

download your chat history from Google Takeout
(optional: extract the JSON file from the .zip archive you get from Google)
upload it to the parser (zip or extracted JSON).

It will then show you a list of all your Hangouts conversations, be it group or one-to-one chats, and you can then view or download single conversations.

Screenshots

Don’t worry, your text will not be all blurry

Caveats

Google switched from Google Talk to Google Hangouts on May 15th, 2013, and the file you get from the Google Takeout export only contains Hangouts chats. This means that there won’t be messages from before that date in your export.

Older chat messages can be found in the “Chats” folder in Gmail. My tool can only work with Hangouts data – if you want to export Google Talk chats too, there’s a python script by Clint Olson (@coandco) here.

Click here to use my parser

If you have a suggestion or found a bug, please do leave a comment below! You can also chat with me in #JayCorner on freenode and QuakeNet.

FAQ

Privacy notice aka What happens to my file when I upload it to your server?

The uploaded file will be stored on the server for 24 hours (there is an hourly cron job that deletes uploads older than 24h), so you have enough time to review your conversations and work with the data. After that, you’ll have to re-upload. I am the only person with access to the server, and I promise I won’t read your chats, you’ll have to trust me on that though There is now (as of 2015-03-15) also a “delete immediately” button at the bottom of the conversation overview, so you can delete your upload when you’re done.

Why does the parser show “unknown_102900492317555965172” instead of the name for some people?

I don’t know. Every person has what Google calls a “gaia_id”, it’s just a long number like 102900492317555965172. This is what identifies that person. In most cases, the person’s name is given in the Hangouts export file too, but sometimes it’s missing. I don’t really know why, maybe they have some stricter privacy settings than most of the people, or maybe they don’t have a Google+ profile, or a private one, or changed their name, … I could only guess. I couldn’t find out the reason so far. Sorry.

How can I save the HTML view with all the images?

Just open the HTML view and use your browser’s “File -> Save as…” function. Make sure to choose “Complete page” or “HTML with all images” or something like that as format, to avoid only saving the html page but nothing else.

Will you publish the source code so I can run the parser on my own server?

Yes and no. I will not publish the source code of the whole parser, and by that I mean the website layout, the uploader, all the methods for exporting/viewing a CSV, XLS, HTML etc. – what I did publish though is the very PHP method that actually parses a Hangouts json file into a PHP array of conversations. You are free to build your own parser around that.

Updates

Update #1 2014-12-29: the CSV link now generates a file download instead of showing a large text box with comma separated text.

Update #2 2014-12-30: I have made some more improvements to my parser and moved the actual parsing code to a separate function, which I published here.

Update #3 2015-01-02: Memory optimizations, fancy HTML5 uploader, view as XML, proper error messages, date picker in HTML view, subtle CSS improvements, bugfixes

Update #4 2015-01-04: Button to download a .zip containing CSVs of all convos.

Update #5 2015-01-10: Added XLSX export (1 conversation per sheet)

Update #6 2015-03-15: Added “delete my upload now” button to the conversation overview after being asked by someone to delete their upload

Update #7 2015-03-21: Added sortable “time of last message” column to conversation list, added expand/collapse to members column when there are more than eight members in a conversation, added message date range filter (makes the conversation list show only conversations with at least one message in the given date range), added selection checkboxes to conversation overview so you can select one, many or all conversations to download as XLSX or zipped CSV. Updated the screenshot of the conversation overview to reflect the changes. Also, the message order in the HTML view can now be reversed (newest message at the top, oldest at the bottom). Some of these changes were based on suggestions by @JMG, kudos to him!

Update #8 2015-04-26: You can now upload the zip file directly instead of first extracting the Hangouts.json file from it and uploading that, this will make uploads much faster and reduce traffic. Thanks @HIM357 for the suggestion.

Update #9 2015-05-29: Fix for chat timestamps being in GMT+1 instead of the user’s local timezone. Thanks @SC for the bug report and @amh for his help with testing the fix.

Update #10 2015-06-13: Added .txt download for single conversations and zipped .txt download for multiple conversations. Thanks @Tomcat for the suggestion.

Update #11 2015-07-06: The hangout parser is now SSL encrypted! Requests to http://hangoutparser.jay2k1.com will be redirected to https://hangoutparser.jay2k1.com. Shoutout to StartCom for providing the certificate!

Update #12 2015-08-07: In the HTML view, the current date is now always visible at the top. It took some CSS fiddlery to make it the way I wanted it to be, and now I’m quite satisfied with it. Thanks to @Ray890 for joining me on IRC and suggesting it!

Update #13 2015-09-23: I made a secondary CSS stylesheet for printing, so if you print the HTML view now, it will look kind of good. I also added a screenshot above to show what it looks like.

Update #14 2015-10-15: Wooooo, 10,000 uploads! I’d never have expected this to be so successful and useful to so many people. Thank you guys! Having coded something that many people use feels great!

Update #15 2016-04-30: Wooooo, 20,000 uploads! This is great. The second 10,000 uploads just took about six and a half months, that’s about half the time of thefirst 10,000. It’s really great to know something I coded is useful to so many people!

426 Comments

Ruchita says:

2017-08-25 at 18:44

This was amazingly hassle free! Thank you so much!

Reply
S Das says:

2017-08-16 at 01:07

Mozilla is crashing when I go to HTML view and then try to use the print option to save it as a pdf.Which is the best browser and what is the best way to save the view in word or pdf?

Reply
1. Jay2k1 says:
  
  2017-08-17 at 12:51
  
  I’m using Chrome and it worked for me in my tests. It can just print webpages to PDF and always did that fine for me.
  
  Reply
  1. Trial Esko says:
    
    2017-08-29 at 19:48
    
    can u please say how to dowload audio files received in hangout chats, please please please
    
    Reply
    1. Jay2k1 says:
      
      2017-08-29 at 21:47
      
      How do you send/receive audio files in hangouts? I couldn’t find a way to do it.
      
      Reply
Dani Marzano says:

2017-08-06 at 03:50

Just wanted to let you know that this is really a huge gift to me. My spouse passed last month and I exported our years long hangouts texts but I am just not feeling up to parsing the json. This did it for me. Thank you. So very very much.

Reply
Carla says:

2017-07-17 at 16:41

I have a university email account and would like to download an archive Hangouts, but Takeout is disabled. How do I go about downloading and archive of my chat history without Takeout.

Reply
1. Jay2k1 says:
  
  2017-07-17 at 16:46
  
  I’m afraid that with Takeout disabled, you’re screwed. Maybe you could find out who has administrator privileges on the email accounts and ask if they could lift that restriction for you. The other way is probably pretty painful: You could open the chat in your browser (https://hangouts.google.com/) and then open the conversation you want to archive and then scroll up until everything is loaded (which, depending on the conversation length, could take ages), and then copy everything into, say, MS Word via ctrl+A and copy paste.
  
  Reply
Jeff Jewson says:

2017-07-06 at 17:49

getting a 404 on https://paste.jay2k1.com/view/678303f8 is there an updated link?

Reply
1. Jay2k1 says:
  
  2017-07-06 at 18:55
  
  Whoops, seems the paste has expired. Here is a new version: https://paste.jay2k1.com/view/5fcebdfe
  
  Reply
Chaudhary Titu says:

2017-06-12 at 18:11

Its actually good
I found it really helpful. Thanks

Reply
G Srini says:

2017-05-30 at 21:54

Is User privacy not a concern here? How about providing this tool for users to download and install on their workstations instead of them uploading the chat to your program.

Reply
1. Jay2k1 says:
  
  2017-05-30 at 22:03
  
  People who are too concerned about their privacy are free to just not use my solution. I once made this tool for myself and chose to offer it to others because I have the knowledge and the resources to host it, things many others probably do not have.
  
  It’s a PHP application that the average user can’t just “install on their workstations” without installing apache and php and tweaking some values like max_execution_time, max_upload_size and so on.
  
  For those who actually do have the knowledge, I’ve published the PHP function responsible for parsing the JSON into a usable array.
  
  Reply
Stephen says:

2017-05-09 at 16:00

It was really helpful. Thanks a lot!

Reply
Jessica says:

2017-05-03 at 15:39

Thank you so much! This is exactly what I needed to provide evidence of stalking and harassment in my court case.

Reply
David says:

2017-04-29 at 00:53

Is there any way for this to identify and list all hangout calls with a person and show the start/end times?

Reply
Pingback: Google Hangouts – Nathan Estell
Roman Smolkin (@pixelbendr) says:

2017-04-18 at 15:44

Thank you, this was very helpful to get an old conversation pulled out in it’s entirety.

Reply
chinlamp says:

2017-04-17 at 11:58

The ‘message date range’ function doesn’t seem to be working at the moment, every time I try to use it and open the file, it still gives me the entire conversation.

Other than that, this tool is incredibly useful, thanks so much for making it.

Reply
ccmia says:

2017-04-10 at 04:39

this was awesome, thank you!

Reply
Kitty Evans says:

2017-03-17 at 02:17

Just wanted to add a note for your readers that do have Gmail. It is possible to see all these hangouts in gmail very easily and search them fairly easily using Gmail. At least it works when you access hangouts from your Gmail inbox which lists chat contacts in a list on the left side and you hover over a name to start a hangout chat with them. Gmail treats these chats like emails. If you filter your gmail by the address of the contact in the search bar such as “from:friend@gmail.com” or “to:friend@gmail.com” in the search results it will list all hangouts chats with that person alongside any actual emails from or to them. You can include search terms in the search bar so if you know you and your friend discussed a movie and you can’t remember what they said about it, you can search “to:friend@gmail.com *movie title or whatever search term*” and it will locate any hangout chats that contain those words. So if you’re just looking for one specific conversation or piece of a conversation, that’s the easiest way to locate it. However, none of that makes it easier to save it and before i found this tool, I was manually copying and pasting all of my chats into Word files which are choking on the size of them, so thank you.

Reply
1. Rachel Worrall says:
  
  2018-01-10 at 17:40
  
  Thanks for this. I am a (heavy) gmail user and have found though that gmail’s ability to find my hangout chats, even when filtered by a specific contact, to be patchy. Perhaps it’s because not all my contacts are on hangouts. For some reason (and I can’t always duplicate this) the search results I get in gmail also differ when I search using gmail on my Nexus, and when I search using gmail on my Macbook Air. I wish I could trust gmail to find chats. But it seems to amount to a bit of the proverbial “Way the Wind Blows” meets the “Needle in a, à la Monet”…
  
  Reply
Evan Thomas says:

2017-03-09 at 02:37

THANK YOU SO MUCH

Reply
Nathan Estell says:

2017-03-03 at 16:36

The CSV exporter is putting all the data in one column with the values separated by semicolons. It would be nice to have each value, like timestamp and sender_name, in its own column.

Reply
1. Jay2k1 says:
  
  2017-03-03 at 17:43
  
  Well, in this case it’s not comma separated values but semicolon separated values. Most programs designed to handle CSV data let you choose one or more delimiter characters, often including comma, semicolon, tab, space etc., so you can just choose to use a semicolon and you’ll have your separate columns.
  Does this help you?
  
  Reply
  1. Nathan Estell says:
    
    2017-03-03 at 18:00
    
    Oh, yes. That was it. Thanks Jay.
    
    Reply
John Doe says:

2017-02-20 at 17:11

The tool throws up SSL errors when I try and access it. Google says StartCom’s certificates have been distrusted due to shady business practices. You could try something else, like Let’s Encrypt, if you want to keep the pages secure. Cheers!

Reply
1. Jay2k1 says:
  
  2017-02-22 at 18:01
  
  That is very weird because I switched to Let’s Encrypt months ago. And that is what openssl s_client -connect hangoutparser.jay2k1.com:443 2>/dev/null | openssl x509 -noout -text shows as well. No idea what went wrong that you got such a warning (I also use the latest Chrome).
  
  Reply
Spacemouse says:

2017-02-08 at 12:25

Thank you, thank you, thank you. Thank you. Your tool saved me a metric tonne of hassle. I’m involved in a messy bureaucratic process and needed a human-readable archive of several years’ worth of chats. You’ve made my day, week, month, and quite possibly quarter!

Reply
1. Jay2k1 says:
  
  2017-02-08 at 16:19
  
  You’re welcome, and thanks for your feedback! It’s comments like this that keep up the motivation to run and maintain this tool
  
  Reply
vareesha Siddiqui says:

2017-02-03 at 20:56

hello i have a question how can i download the conversations in HTML format?

Reply
1. Jay2k1 says:
  
  2017-02-03 at 20:59
  
  Just open the HTML view and use your browser’s “File -> Save as…” function. Make sure to choose “Complete page” or “HTML with all images” or something like that as format, to avoid only saving the html page but nothing else.
  
  Reply
  1. vareesha Siddiqui says:
    
    2017-02-04 at 09:00
    
    but it will open in chrome, i wanted to know if there is a way just like downloading in TXT or any others, so it will not open in chrome, i want to download in html type of format in which it is easy to read and follow everything.
    
    Reply
    1. Jay2k1 says:
      
      2017-02-04 at 15:50
      
      Yeah, you open it, then you can save it. Currently there is no other way to do it.
      
      Reply
Michael Blanchette says:

2017-01-25 at 18:17

Thank you for this. My fiancee past away and I wanted to backup up our long distance long term Hangouts history. This allowed me to back it up to my computer including pictures! Use the donation for a beer or coffee or, in honor of Eva, her favorite drink, a Margarita!
Thank you
Mike

Reply
Winget says:

2017-01-21 at 18:38

Hi Jay, thank you for creating this tool and making it available. You can’t imagine how grateful we are to be able to access this information and have it all in downloadable in one file. Heartfelt thanks!

Reply
Winget says:

2017-01-21 at 13:55

I wanna permanently delete from everywhere a chat. What should I do. (Its on hangs. I have deleted it already. The history button was on)

Thank you

Love

Winget

Reply
1. Winget says:
  
  2017-01-21 at 18:37
  
  halaiohfwhfoiwhfoiwhf vihvjwqv Hi Jay, thank you for creating this tool and making it available. You can’t imagine how grateful we are to be able to access this information and have it all in downloadable in one file. Heartfelt thanks!
  
  Reply
S&V says:

2017-01-15 at 04:58

Hi Jay, thank you for creating this tool and making it available. You can’t imagine how grateful we are to be able to access this information and have it all in downloadable in one file. Heartfelt thanks!

Reply
Rain says:

2017-01-10 at 16:48

Do you know of any tools that can take this exported data and import it into the stock android sms database? I’m trying to move away from Hangouts.

Reply
1. Jay2k1 says:
  
  2017-01-10 at 16:52
  
  Yes, I actually do! Find it here: https://play.google.com/store/apps/details?id=de.lweber.hangouts_convert
  
  Reply
  1. Venkat Lakshminarayanan says:
    
    2018-06-18 at 22:02
    
    Hi, is there an updated link? It looks like the app was removed. Thanks!
    
    Reply