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.


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


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.


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.


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 will be redirected to 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!


  1. It looks like it may also be possible to save everything directly to mbox format using Google Takeout, by selecting just the Chat label in a Gmail export, and that that might include both Talk and Hangouts messages… Certainly, in the Gmail web app the Chats (not Chat, a difference which may or may not be significant,) folder covers messages from 2009 to present for me.

    1. Having received the Takeout link now and imported the mbox file into Apple Mail, I can confirm it does include both Talk and Hangouts messages, but the latter aren’t useful. Apple Mail can read all the Google Talk messages fine: assigns the correct dates and names to them. However, the Hangouts date range is a mess. All of those are shown as today’s date and mostly without a helpful sender/recipient. There are also no images included (which is fine for Talk, as it was text only).

      Hope that’s useful extra info, anyway. It isn’t necessary to use IMAP; although maybe that would bring in the Hangouts data correctly…

  2. No HTML view when I tested with several exported JSON files. Do you have the names of the relevant fields posted somewhere that contain the actual communications?

    1. Hi Mike,

      sorry, I had a bug with the pagination mechanism. It should work now.

      Merry Christmas!

  3. Thank you. This has been a very helpful tool. I had over three years of hangout chats with pictures and everything. Wanted to keep it as memory sake. I used the HTML format, copied page by page and export as PDF and also copied into word doc.

  4. I wish I’d found you sooner. This has been a great help to me. Thank you.

  5. Hi Jay2k1,

    I absolutely love this tool and have used it many times over the past year. I’ve been having a problem for the last week or so though. My file appears to load fine but I get no results. The progress bar finishes and then… nothing. I tried switching from Chrome to Firefox with the same result. I tested with a smaller JSON thinking maybe it was just too large of a file but got the same. I even tried extracting a fresh copy of the previous successfully used JSON and still nothing. Any idea of what could be causing it?

    1. Hi, sorry for that, this was a newly introduced bug which I have now fixed. Apologies!

      – Jay

  6. Jay,
    I do love this tool and would pay for it if needed there isn’t anything I have found that is this capable.

    Ran into a bit of a problem. It crunches my file for about 5 minutes finally getting to 100% but never gives me the conversations, and taskmanager says it is still running after about 30 minutes. The many times I have run this before it has never taken this long.
    I even restarted Windows and started clean but no help.

    I will let it sit but don’t think it will ever complete.

    Any ideas?

    The hangouts.json file is 20 MB — maybe to big?


    1. I am having the same problem as above – it will get to 100%, but then show a blank screen. Any help would be appreciated.

    2. I have the same issue with my .json file but mine was 56MB.

      Do you have any solution for this already?

      1. Hi, sorry for that, this was a newly introduced bug which I have now fixed. Apologies!

        – Jay

    3. Hi, sorry for that, this was a newly introduced bug which I have now fixed. Apologies!

      – Jay

  7. Hello,
    With the move Google is making from Hangouts to Google Chat, are there any plans to update the JSON decoder for the format that Google is now using. Messages.json from the export of Google Chat history doesn’t work on the current decoder.

    Thanks for a wonderful app!

  8. No idea how to read my hangouts conversations, then I found this, easy to use and a fantastic piece of programming.

  9. Hi Jay,

    I love this tool it makes extracting conversations effortless from Google and I’ve used it alot.

    I have noticed that the date and Time are wrong, but it doesn’t do this every time. Sometimes it comes out perfect and at other times its using GMT or something to make it completely out of sync.

    Is there a way to correct this in the JSON before running your tool? Or is there something I need to do that I’ve missed?


  10. Would you happen to know how I can *import* the data from one of the saved files into a stock sms app on my android?

    I’ve found more than a few tools for this on GitHub , and even got so far as to get one of them running in Termux (Linux emulator that can run custom packages; python, git, ssh, etc..), but I’m a total noob and dunno what commands to use to actually do what the tools were written to do lol. They all don’t have any in-depth tutorials, probably because they were intended to be used by people who know wtf they’re doing.

    I’ve tried almost every “SMS Restore” type of app on the playstore to no avail.. They all fail or crash.

    … any ideas would be appreciated.

    1. Sorry, that I don’t know Back when I made the parser, there was one tool that made an XML file supposedly compatible with an android app called “SMS Backup & Restore”, but apparently that project was abandoned a while ago.

      The only hope is maybe that because Google is abandoning Hangouts, a few tools and tutorials might pop up over the next few months because you’re certainly not the only one with this problem I could imagine.

      1. Yeah, I do remember once using that specific method way back! Unfortunately that app no longer works and I can’t remember specifically where I converted the Json to XML. I’ll have to keep digging.. Might be able to find an older version of the apk, but I’ve spent like 4 hours already trying to find the correct tool that will covert the json without any luck.

        It’s honestly BS how Google has handled their switch to Voice from Hangouts. Voice doesn’t even work for a LOT of people right now, including myself (why I’m here lol); not getting sms / call notifications, calls dropping, etc.. and the app is really buggy.

        I’ll reply here again if I find a solution in case anyone else happens to find this post later on. There definitely will be more people looking for options!

        Regardless, thanks for the help (and for that parser tool so I can at least read my old convos if need be).

        1. Update! I found a way to restore sms messages from Hangouts with the Backup & Restore app. The most recent Google Takeout for Hangouts has a Json file in it that can be converted to XML with this tool:

          And that XML can be seen / restored as a normal backup would on the most recent Backup & Restore app.

          This is the only python script I could find that is written specifically for the Backup & Restore app – every other Json to XML converter I tired either didn’t work with any restore app or was too complicated to use.

          Hopefully this info helps anyone else lurking the abyss for a solution like I was. I got all 12,000 of my messages restored on my phone now. I’m also never committing to a Google app like that again.. ever.

  11. Hi. This tool you built is everything I’ve been looking for and is working great except for the final step I’m trying to do, which is save my hangouts/chat history as a PDF with all the lovely HTML formatting you set up. With a shorter conversation, this is no issue. I can click to view it as an HTML and then (in Chrome), press control P, and then choose save as PDF and get what I want.

    However, with my longer conversations (like all the chats I exchanged with my husband since 2014), Chrome’s print window ends up freezing and saying the print preview can’t load and just won’t finish saving as a PDF. Which is understandable. I’m sure that document would be one zillion pages long.

    I have no idea if you are still active here, but if so, would it be possible to add the ability to filter the HTML view by date range so that I could view (and print to PDF) shorter sections of the total conversation?

    1. Hi Jill, I’ll send you an e-mail, let’s see if we can work something out.
      – Jay

      1. Hi Jay2k1,

        First off, this tool is AMAZING!! THANK YOU. Finally I can make a human friendly backup of my Hangouts!!

        I am having the same issue as Jill. It really struggles to create a PDF that is almost 2000 pages long. In addition, I hit a rate-limit error on rendering the images in html view because there are so many. It would be really cool if on the main page when you change the date filter, when you click HTML option that it is limited to that filtered date range.
        That way I can more easily render small batches of my Hangouts and be able to save to PDF (like by month, or something).

        Would love to discuss further!

        1. Hi Marie,

          I had worked out a test solution with Jill which I have only discussed via e-mail so far. Currently, the HTML display has a new pagination feature now, making it show 10,000 messages per page. However if this number is too big for you, you can change it in the URL.

          Click the URL, at the very end you’ll see a string like &convo=23&page=1&perpage=10000. The first is the ID of the conversation you are viewing, the next is the page number you want to see and the last is the amount of messages to be displayed per page. You can change it to a lower value. Please give it a try and tell me what number works best for you.

    1. Michael,

      unfortunately, I do not know how to write actual Windows applications (or for any OS, for that matter), so I can’t do that, sorry.

  12. Thanks for the app, this means a lot to my girl who just deleted her iphone messages but I use hangouts and couldnt export back to her.

  13. That was awesome, idk wut the point wuz of wth they sent me. I hope where eva u work u gets paid the big bucks. This …. *shurg* tool magic! U can tell by this msg’ed y I soooo needed this! TY so much! Sincerely Nicole

Leave a Reply

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