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!

319 Comments

  1. Thank you for having such a wonderful tool online to help others out that don’t have a clue how to do such things.

  2. Hello Jay,

    Is there any way to transfer all hangout chat from old gmail account to new one? as i used google takeout but it was not transferred proper hangout chat..

    Rgds
    Prakash

    1. Hi Prakash,

      I do not think there is a way to import a hangouts JSON dump to a Google account, sorry.

      Jay

  3. This was a life saver! I am about to go to court to save my daughter from a horrible, horrible human being (if you can even call him that!). Some of the evidence was captured in a very long FB chat thread and FB does not offer such simple and common technologies as printing (they leave so much to be desired!). You are my hero!!

    1. I really hope you mean Hangouts and not Facebook, otherwise my tool is probably useless
      In this case though, I wish you all the best! I’m glad my tool is so useful to you, it’s more than I have ever imagined.

  4. Any chance you would publish source for the full parser including upload function? From a privacy standpoint, I can’t upload my ZIP file to a third party source. Thanks,

    1. Hi Ben,

      I understand your privacy concern, but I currently do not plan on releasing the whole source code. The biggest part is the actual parsing function though, and this I already published. It’ll give you all messages/conversations in one big PHP array. I’ve seen 1-2 python implementations around too.

      Jay

  5. Could something like this be used to convert the Hangouts Chat history into format that could be restored to Google Messenger as sms so can use Messanger going forward for text messaging while preserving the history from Hangouts?

    1. Hi Mark,

      I do not know if Google Messenger has a way to import data, nor what format it would use, so I can’t tell.

      Jay

  6. Jay, this is a fantastic tool and it is really helping me. You have done something wonderful – you made something that made life easier and better for people. Thank you so much.

  7. Wonderful tool. I was really struggling with backing up/archiving important text messages sent via Google Hangouts. Thanks!!

  8. Hello! Your parser is super useful, I used it before, but I lost the json file that I was opening with it. Is there any record kept on your server of files that are opened using your parser? I would like to recover that json but I cant find it anywhere, but I know I uploaded it onto your website to open it multiple times.

    1. Hi and thank you for your nice words! As for old JSON files:

      If you used the parser less than 24 hours ago (and didn’t press the “delete now” button at the bottom), your file is still there and you just need to remember the URL (maybe look at your browser history).
      If your upload is older than 24 hours the file has definitely been deleted by now and I have no way to get it back. I run a cron job, that’s a scheduled task on linux, once per hour which deletes all uploads that are older than 24 hours. And since they are stored in /tmp, the linux folder for temporary files, they are being excluded from the daily server backups.

      But… why don’t you just go to Google Takeout and download a new export?

    1. I’m afraid you can’t. I’m displaying all the names that are in the file, if you see contacts named “unknown_1234567890” then they do not have a name set in the file. In that case I show “unknown” and their chat id number.

      I don’t exactly know when or why that happens – maybe they are no longer in the group chat or they removed their Google account or something. But obviously I can only display what’s in the file.

  9. Hangouts archive doesn’t back up SMS guys. If you want to back up SMS, use http://www.printtextmessages.net/. There are apps for Android (which I have used and can confirm works) and for iPhone. Can’t remember if it costed money or not but I had some important memories in SMS so I’m sure it was worth it.
    I actually like the export of that app better than the Hangouts Parser (but THANK you for making this) because it has “===============” separating each message, making it way easier to parse in a program. Would it be possible to get this or a similar separator in the Hangouts Parser? Thanks.

  10. Thank you so much! Google should pay you for this one!!! I am bringing my future wife from Kenya to the USA. This allowed me to satisfy the Lawyers on the proof of our conversation for immigration.

    Thank you so very much!!!!

  11. Jay, I am unable to get my SMS messages from the parser only gchat messages. Can this be fixed?

    1. Are you really using Hangouts for SMS? Other users can see their SMS just fine, so I suspect your SMS are not in your Hangouts export for some reason.

  12. Excellent! Thanks so much!

    Only feedback I have is instructions or functionality on how to convert to a message format and put it into my gmail account under the chats tag, so that it at least has a home with the old gtalk conversation threads.

    I also am wondering if there’s a way to pull messaged pictures and include them in the html export, but I suppose if google only gives a json file, they aren’t included directly in the takeout file.. Though it would be some truly epic code to map to the google+ photo album, download the pictures, and include them in the html file.

    At the very least, I have the pictures and the messages, so I got what I came for so the stopgap is working!

    1. Unfortunately I can’t help you with the Gmail question, I don’t have a Gmail account and do not know how Tags work, let alone what format these old gtalk chats are (and if you can add more).

      Regarding images, you are assuming correctly. Google doesn’t include the images in the exports, JSON is plaintext anyway. Google marks images as attachments and includes a link pointing to the image in the export. I am using the links to display the images. They look like this: https://lh3.googleusercontent.com/IsGo4lObh7wj/3nzTobHAnS2X/LkkeZt2SR1dG/hTZH2pCoMFPg/s0/2015-01-01.jpg

      What you can do is just open a conversation in HTML view and then use the “Save As…” feature of your browser. In Chrome it can be found in “Menu” -> “Tools” -> “Save page as…” or press Ctrl+S. This way you can save the current website (including images in original resolution) on your computer.

  13. Hello Joshua,

    I need to backup my hangouts but the SMS’s are missing received attachments. I use hangout Google Voice integration and I’m able to receive MMS messages with attachments though it. I would like to be able to backup all the messages including the images but as the current script stands that is not possible.

    I went ahead and downloaded the PHP script and modified it so that it uses the same code for both REGULAR_CHAT_MESSAGE and SMS, and it handles the images fine, IE:

    case ‘SMS’:
    case ‘REGULAR_CHAT_MESSAGE’:

    If you could fix this ASAP, I would be so thankful! I really want the ability to see those incoming attachments also.

    Thank You!

    1. Hi Brandon,
      although my name is not Joshua I went ahead and made your suggested change.
      Can you test and confirm it works for you?

  14. This worked great! I saved the html view page per person, the css files and some of the javascript into a folder. Now I can see my chats more visually in my browser, with images included, too.

    1. I’m happy you liked it! Someone already suggested making this another download option (a HTML bundle for exactly this reason), when I get around to it I’ll probably code that soon.

  15. I “accidentally” deleted my hangout history with one person. However, I understand it still exists in her hangout history. Is there any way I can use her hangout history with me to “restore” my hangout history with her?

    1. As far as I know, there is no way to (re-)import a Hangouts export. The only thing you could do is have her either send you her whole Hangouts.json (the export itself) or have her use my parser and extract your chat to one of the available formats.

      1. Thank you for replying.

        Would that .json contain only her and my conversations or would it include her conversations with everyone she had conversations with?

        Thanks you.

        1. A Hangouts export from Google Takeout always contains ALL chats. You cannot select individual chats there. By the way, are you sure you really deleted the chat and did not just archive it? I just tried deleting a hangout, all I could find was how to archive it…

          1. Well i have an archive and a delete button – I am almost positive I selected the delete button because it gave me a warning message.
            How do I look for archived hangouts so I can see if hipefully I did that instead of delete?

            Thank you.

          2. I just found out how to check for archived hangouts and it says I have none – so I must have deleted it.
            Thanks for the idea.
            Thank you for your help.
            Regards,
            Donald Cox

    1. Emoticons are unicode characters. Currently, I replace them by text emoticons in the parsing process. Leaving the original emoticon characters might work at least for the HTML view, but I’d have to look into that (I don’t specify a font for the layout, so different browsers might choose different fonts which may or may not support emoticons) – I guess it’s not worth the effort. You can try to convince me though

  16. anyway you can make this parser a download, so i can run it locally on my machine. Its not that i dont trust that its deleted in 24 hours, but being someone with an information security education, i dont trust anyone on the internet. Also i am in the middle of a major custody dispute that likely wont be over for years, if you stop supporting and take down the site i dont know if anyone would pick up where you leave off and i would be stuck with the json file pain in the neck. I love and appreciate the work that you have done with this parser. I plan on using it at least once a month to get 1 conversation out of google hangouts.

    1. Hi Joshua,
      I understand your concerns but unfortunately I (literally) can’t do that. I am a sysadmin, not a developer, I only know some PHP/JS/HTML but no language that would allow me to make a standalone application for any OS. I made this for myself because I needed a tool like this and couldn’t find any, and then thought I’d put it online so others could use it too, that’s all there is to it.
      You can however download the PHP class the parser uses here and use it to write your own parser. There are also a few python hangout parser scripts on github, just google “python hangout parser”, if you’re more of a python person. If you can code in any language, you’ll probably be able to at least understand what my php class is doing and adapt it in your language of choice.

    2. Same for me, I just wonder how many people have credit card information and other stuff in their JSON file. This program would be nice to have, but the lack of data security is a pain in the….

      Too bad, got to search for an alternative, which is not web-based. Nobody can check if those files uploaded are not checked for “interesting” data. Missing “impressum” does not add more safety…

      1. I don’t regularly send my credit card information to my friends via hangouts, not sure about you However I understand your privacy concerns and to be honest, I’m not sure if *I* would upload my Hangouts data to a website of someone else. It’s fine, to use it you need to trust me/the parser enough, and I really cannot blame you if you don’t.
        I, however, don’t really have a way to add more transparency. I could show you a screenshot of the cronjob that regularly deletes the uploads but of course, but that could be faked, and I could still read the files as long as they are on the server or filter them for certain keywords.

        But I don’t.

        As for the impressum, just look at this blog’s one…

Leave a Reply