Skip to content

Latest commit

 

History

History
75 lines (64 loc) · 7.14 KB

README.md

File metadata and controls

75 lines (64 loc) · 7.14 KB
Raw

OSX Messages Exporter

Exports Messages' conversations to HTML files. This includes iMessages, SMSs, and group conversations.

This script processes all of the existing conversations in the Messages app, logs them to a separate backup database in your specified output directory, and then generates HTML files for each conversation, mimicking the look and feel of Messages conversations. (See example.html for an example of one of the HTML files.) Attachments are saved in a separate directory for each conversation.

It will try and match phone numbers and email addresses to real names, using your Mac's Address Book. It should be able to find contacts that are stored either on your Mac or in iCloud, if they've had time to sync to your Mac (typically only a few minutes).

Note that if you are running OSX Mojave or later, you will probably need to give Terminal full disk access in order for OSX Messages Exporter to work.

With the -f or --flush option, you can force the script to delete the existing backup database and regenerate everything. (Without this option, you could maintain backups of conversations even if Messages deletes them, accidentally or not.)

With the -r or --rebuild option, you can regenerate the HTML files from the backup library.

With the -d or --database option, you can run the export on a specific Messages database file. By default, the script uses ~/Library/Messages/chat.db. Note that when using this option, attachments will not be saved, since the assumption is that the paths to the files are from another machine.

With the --date-start and --date-stop options, you can limit the dates that are added to your backup. Note that this only applies to new messages being exported; it won't remove messages outside of those dates that have already been exported.

Usage

$ messages-exporter.php [-o|--output_directory output_directory]
                        output_directory: a path to the directory where the messages should be saved. Save files in the current directory by default.
                        [-f|--flush]
                        Optionally, flush the existing backup database, essentially starting over from scratch.
                        [-r|--rebuild]
                        Optionally, rebuild the HTML files from the existing database.
                        [-d|--database /path/to/chat/database]
                        Optionally, specify an alternate database file if, for example, you're running this script on a backup of chat.db from another machine.
                        [--date-start YYYY-MM-DD]
                        Optionally, specify the first date that should be queried from the Messages database.
                        [--date-stop YYYY-MM-DD]
                        Optionally, specify the last date that should be queried from the Messages database.
                        [-t|--timezone "America/Los_Angeles"]
                        Optionally, supply a timezone to use for any dates and times that are displayed. If none is supplied, times will be in UTC. For a list of valid timezones, see https://www.php.net/manual/en/timezones.php
                        [--date-format "n/j/Y, g:i A"]
                        Optionally, supply a output dateformat to use. If none is supplied, a date will be shown like "3/5/2021, 12:43 PM". For a list of valid timezones, see https://www.php.net/manual/en/datetime.format.php
                        [--no-video-preload]
                        If set, the HTML markup will include a 'preload="none"' attribute so on larger chats not all video files will be preloaded in a browser
                        [--summary]
                        If set, the script will return a small summary with number of exported messages/chats and possible errors (missing attachments)
                        [--html-head-template /path/to/template/file.html]
                        If set, the script will use the specified filename inside the HTML <head> section. Variable substitution with {{CHAT_TITLE}} is available. Use this to use custom CSS rules or inject i.e. JavaScript
                        [--html-toc-template /path/to/template/file.html]
                        If set, the script will use the specified filename inside the HTML <head> section for the TOC. Variable substitution is available: {{TOC}} for the TOC loop (see below)
		                [--html-toc-loop-template /path/to/template/file.html]
		                If set, the script will use the specified filename inside the HTML TOC. Variable substitution is available: {{FILE}}, {{TITLE}}, {{DATE_FROM}}, {{DATE_TO}}, {{MESSAGE_FROM_BODY}}, {{MESSAGE_TO_BODY}}.
                        [--safe-filenames]
                        If set, directory and filenames will only contain characters from A-Z, no special characters, no spaces.
                        [--contact-csv /path/to/contacts.csv]
                        By default, contacts are matched by several lookup to system files, however a lookup may fail. In this case you can provide a CSV file with two columns \"Number,Name\" (Number can be an eMail address, too) that resolves a iMessage ID to a readable name. The CSV will take precedence over other address books, so you can use it to even override specific contact names that exist. Ensure the CSV file matches your local charset, use comma as separator, UNIX newlines and no enclosing quotes.
                        [--skip-attachments "all|a,i,v,d"]
                        When set to "all", all attachments will be replaced by a simple placeholder. Can be used if you just care about plaintexts. If no parameters to this is specified, all attachments are skipped. Else you can specify a comma-separated list of characters to each attachment type to skip (a=audio, v=video, i=image, d=document)
                        [--progress]\n
                        When set, you will get a (simple) progress report while compiling data and output.
                        [--max-messages XX]
		                Debugging: When set, you can specify the maximum of messages to write for each chat; allows easier debugging.

Caveats

  • If you run the script, and then delete a conversation in Messages, and then run the script again, the backup of the deleted conversation will not be deleted. This is by design.
  • If you try to run this script via a LaunchAgent or some other automated means, it may fail because the Messages database file is protected by Full Disk Access starting in Mac OS Mojave. To get around this, you'll need to do the following:
    • Create a shell script that runs OSX Messages Exporter, like this:
      #!/bin/bash
      php /path/to/OSX-Messages-Exporter/messages-exporter.php -o /path/to/output
    • Package that script into an app using Platypus
    • Give the app Full Disk Access
    • Modify your LaunchAgent (or other automated script) to run the app instead of running OSX Messages Exporter directly.

Questions?

Email me at [email protected]. (Enhanced by Garvin Hicking, @supergarv on Twitter)