How to export and backup your Google Hangouts chat history

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…

  1. download your chat history from Google Takeout
  2. (optional: extract the JSON file from the .zip archive you get from Google)
  3. 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

conversation list
conversation list
HTML view
HTML view
text view
text view
XML view
XML view
CSV view
CSV view
CSV view
Print view

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!

427 Comments

  1. Would be great if there was a “Save all as HTML” option so I could upload the JSON and then get all of the conversations saved in different folders. I know, I’m being lazy.

  2. Hi sir or madam,
    Thank you for your amazing work thanks to you I can download years of chat with my lover but sorry for that I don’t want to be rude but there is some messages that doesn’t appear and it makes the conversation looks weird like the other person has not replied but in fact he did. Do you know what I can do to recover every single message ? I read it in the pdf format version.

    Thank your in advance for your response and have a great day

  3. Merging chats would be simple, user defines target UserIDs with check boxes on form, UserIDs in JSON file that match check box values are replaced with UNIQUE value, run script as usual.

  4. Aw dang, my file is 560MB which is over the 500mb limit. Is there anything I can do?

    1. You can zip your JSON file and upload the zip. Don’t upload the original zip file though, as it also contains images.

  5. Fantastic tool. Probably going to get a lot busier now that Google is axing Hangouts! Thanks so much for making this available. One hopes Google will make some sort of migration tool available into Messenger so people who used Hangouts don’t find themselves “orphaned”, but your tool provides a great historical record.

  6. That was bloody brilliant. I wanted to save all the hangouts messages I had from my late husband before I archived it away. Perfect I changed it to HTML then saved it as a PDF in Google Drive, got it for keeps now.

  7. Hi, thanks for your tool, it’s a godsend. Wanted to let you know that it seems the local timezone is broken, at least in the HTML version. I’m seeing timestamps that look like GMT, which has the unfortunate side effect of assigning some messages to the wrong day. Thank you!

  8. Can you please help to guide me on finding the way of getting history messages from chat.google.com.
    Kindly suggest an idea will do the follow up
    (between tool helped to retrieve old messages from hangouts , it is really helpful .Thanks lot)

  9. Can any one please help to get the history messages from chat.google.com
    (between tool helped to retrieve old messages from hangouts , it is really helpful )

  10. I love you I love you I love you. thank you so very much for this information. I was trying so many ways to get a copy which was very long. Can’t believe Google could not make Hangout so simple for the users. Thank you

  11. Thank you for taking the time to put this software up online. I wish Google would create something similar to use.

  12. Hi, if i zipped the hangout messages . Does it still show the messages on hangout app?.

  13. I downloaded the Hangouts app onto my iPhone 7+, yet when I open Goggle mail I see no conversations I Archived while in the Hangouts app. Also, when I scroll to the top of a conversation in Hangouts app it seems to be cut off at a pre-set amount. Is it possible to retrieve earlier conversations?

  14. Jay, thank you for this converter. There seems to be a bug with converting to .xslx though I just used the other formats. Beer money to follow.

  15. you should post an ethereum tip address so i can tip you for this. basically saved my ass

  16. is it possible for you to enable files larger than 500mb? or do you know of another way to parse files larger than that/break it down? my chat history is 950mb and i have no clue how to get at it ^-^;; thanks!

    1. Hank, I doubt that your actual chat history is >500MB.

      If you tried to upload the very zip archive you got from Google Takeout, don’t do that. They started including all the images in there. I only need the file called “Hangouts.json”. So go and open that zip, extract the JSON file and upload just that. You can zip that file before uploading, then it will be even smaller.

      1. thanks, while the json file itself is 923mb (i was only uploading that!) putting it in a zip folder got it down to 45mb. so, thanks!

        1. Wow, then you must be a very chatty person (or in lots of busy group chats) 😅 glad zipping worked out for you.

        2. also thank you so much for this tool; finally able to reread this stuff without having to scroll back through 10,000+ pages!

  17. Thanks for creating this tool! I’m also looking for a way to take the exported data and import it into teh stock android SMS database, either using a backup app (like Titanium Backup or SMS Backup and Restore), or by directly merging with the stock database. Is this currently possible? The app store link above no longer connects to an app. Thanks!

    1. I’d love to do this as well. I got here searching for a way to get my Hangouts messages into Android Messenger so that I can leave Hangouts behind. It looks like the app that can convert this to an SMS Backup & Restore file was available as recently as 8 months ago, but it no longer exists on the Google Play store. It seems like it would be easy for a programmer to take this one step further and change either the XML or a CSV into the appropriate format, but I’m not one. Still, I’m going to have a go at converting one of my smaller XML files to see if I can find a way to make it work. Thanks for this tool!

      1. Wow, the 300th comment

        Back when I was trying to find a way to export Hangouts messages, I had found the app I linked in the earlier comment too. Actually, you needed two Android apps as it seems – the one called “Hangouts Chat Export” which would convert the JSON into a special XML format readable by another App called “SMS Backup & Restore”, and that very App to import it into the SMS application of your phone.

        A quick Google search for “SMS Backup & Restore” told me that it was recently bought by another company, so it might have changed. However the Play Store page of the first App said in the description that there are other apps capable of importing the same XML scheme too, like TextSecure.

        As for the app that transforms your JSON into XML in the first place: I have talked to its developer. He said, after Google changed the format of the JSON exports in March 2018, his app did not work any more and he’d have to put more time into rewriting it than he had available. Consequently, he removed it from the Play Store.

        Now if you wanted to use my parser and then use its output to create an XML file compatible with apps like “SMS Backup & Restore”: The XML format is somewhat documented here. It shouldn’t be too hard to do, but it probably expects a phone number for each conversation. The now non-existent Android app let you map conversations to phone numbers on your phone. That is kind of hard to do on your desktop computer because you can’t just choose from your address book.
        Good luck!

  18. Would it be possible to get an offline version of the parser? My JSON file is over the 500MB limit. Even if it’s just the source code, I can work with that.

    1. You can zip the .json and upload that.
      I’ve just open sourced the JSON-to-PHP-array parsing function, not the whole “web app”, so there’s no offline version, sorry.

    1. Sign in to your google account
      Go to ‘My Account’
      Under ‘My Preferences’ you have ‘Delete account and services’. Follow that and you should be able to delete it.

Leave a Reply to Jay2k1 Cancel reply

Your email address will not be published. Required fields are marked *