{"id":13586237,"url":"https://github.com/caleb531/imessage-conversation-analyzer","last_synced_at":"2025-04-07T14:34:13.484Z","repository":{"id":65378504,"uuid":"295061013","full_name":"caleb531/imessage-conversation-analyzer","owner":"caleb531","description":"Gathers metrics of your choice for the entire history of a macOS Messages conversation","archived":false,"fork":false,"pushed_at":"2024-04-03T00:44:20.000Z","size":351,"stargazers_count":21,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-04-16T18:46:16.039Z","etag":null,"topics":["conversation","imessage","pandas","phone-number","python","texting"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/imessage-conversation-analyzer/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/caleb531.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-09-13T02:11:50.000Z","updated_at":"2024-08-01T16:32:18.116Z","dependencies_parsed_at":"2023-01-20T07:55:17.913Z","dependency_job_id":"2d139b77-0659-4e92-bcf8-9141b7e72eb2","html_url":"https://github.com/caleb531/imessage-conversation-analyzer","commit_stats":{"total_commits":88,"total_committers":1,"mean_commits":88.0,"dds":0.0,"last_synced_commit":"f146435a44605a3f9f754ea44c1a4a9dc68ec018"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caleb531%2Fimessage-conversation-analyzer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caleb531%2Fimessage-conversation-analyzer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caleb531%2Fimessage-conversation-analyzer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caleb531%2Fimessage-conversation-analyzer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/caleb531","download_url":"https://codeload.github.com/caleb531/imessage-conversation-analyzer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247670574,"owners_count":20976598,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["conversation","imessage","pandas","phone-number","python","texting"],"created_at":"2024-08-01T15:05:25.153Z","updated_at":"2025-04-07T14:34:13.477Z","avatar_url":"https://github.com/caleb531.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# iMessage Conversation Analyzer\n\n*Copyright 2020-2025 Caleb Evans*  \n*Released under the MIT license*\n\n[![tests](https://github.com/caleb531/imessage-conversation-analyzer/actions/workflows/tests.yml/badge.svg)](https://github.com/caleb531/imessage-conversation-analyzer/actions/workflows/tests.yml)\n[![Coverage Status](https://coveralls.io/repos/caleb531/imessage-conversation-analyzer/badge.svg?branch=main)](https://coveralls.io/r/caleb531/imessage-conversation-analyzer?branch=main)\n\niMessage Conversation Analyzer (ICA) is a fully-typed Python library (and CLI\nutility) that will read the contents of an iMessage conversation via the\nMessages app's database on macOS. You can then gather various metrics of\ninterest on the messages.\n\nMuch of this program was inspired by and built using findings from [this blog post by Yorgos Askalidis][blog-post].\n\n[blog-post]: https://medium.com/@yaskalidis/heres-how-you-can-access-your-entire-imessage-history-on-your-mac-f8878276c6e9\n\n### Caveats\n\n- Group chats (three or more people) are not supported at this time\n- This program only runs on macOS\n\n## Installation\n\nOpen a Terminal and run the following:\n\n```sh\npip3 install imessage-conversation-analyzer\n```\n\n## Usage\n\nThe package includes both a Command Line API for simplicity/convenience, as well\nas a Python API for developers who want maximum flexibility.\n\n### Command Line API\n\nTo use ICA from the command line, run the `ica` command from the Terminal. The\nminimum required arguments are:\n\n1. A path to an analyzer file to run, or the name of a built-in analyzer\n2. The first and last name of the contact, via the `-c`/`--contact` flag\n   1. If the contact has no last name on record, you can just pass the first\n      name\n\n#### Example\n\n```sh\nica message_totals -c 'Jane Fernbrook'\n```\n\nThe following outputs a table like:\n\n```\nMetric               Total\nMessages             14535\nMessages From Me      7289\nMessages From Them    7246\nReactions             5050\nReactions From Me     3901\nReactions From Them   1149\nDays Messaged          115\nDays Missed              0\nDays With No Reply       0\n```\n\n#### Built-in analyzers\n\nICA includes several built-in analyzers out of the box:\n\n1. `message_totals`: a summary of message and reaction counts, by person and in\n   total, as well as other insightful metrics\n2. `attachment_totals`: lists count data by attachment type, including\n   number of Spotify links shared, YouTube videos, Apple Music, etc.\n3. `most_frequent_emojis`: count data for the top 10 most frequently used emojis\n   across the entire conversation\n4. `totals_by_day`: a comprehensive breakdown of message totals for every day\n   you and the other person have been messaging in the conversation\n5. `transcript`: a full, unedited transcript of every message, including\n   reactions, between you and the other person (attachment files not included)\n6. `count_phrases`: count the number of case-insensitive occurrences of any\n   arbitrary strings across all messages in a conversation (excluding reactions)\n\n#### Filtering\n\nThere are several built-in flags you can use to filter messages and attachments.\n\n- `--from-date`: A start date to filter messages by (inclusive); the format must\n  be ISO 8601-compliant, e.g. YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS\n- `--to-date`: An end date to filter messages by (exclusive); the format must be\n  ISO 8601-compliant, e.g. YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS\n- `--from-person`: A reference to the person by whom to filter messages;\n  accepted values can be `me`, `them`, or `both` (the default)\n\n\n```sh\nica message_totals -c 'Jane Fernbrook' --from-date 2024-12-01 --to-date 2025-01-01 --from-person them\n```\n\n#### Other formats\n\nYou can optionally pass the `-f`/`--format` flag to output to a specific format\nlike CSV (supported formats include `csv`, `excel`/`xlsx`, and `markdown`/`md`).\n\n```sh\nica message_totals -c 'Jane Fernbrook' -f csv\n```\n\n```sh\nica ./my_custom_analyzer.py -c 'Jane Fernbrook' -f csv\n```\n\n#### Writing to a file\n\nFinally, there is an optional `-o`/`--output` flag if you want to output to a\nspecified file. ICA will do its best to infer the format from the file\nextension, although you could also pass `--format` if you have special filename\nrequirements.\n\n```sh\nica transcript -c 'Thomas Riverstone' -o ./my_transcript.xlsx\n```\n\n### Python API\n\nThe Python API is much more powerful, allowing you to integrate ICA into any\ntype of Python project that can run on macOS. All of the built-in analyzers\n(under the `ica/analyzers` directory) actually use this API.\n\nHere's a complete example that shows how to retrieve the transcript of an entire\niMessage conversation with one other person.\n\n```python\n# get_my_transcript.py\n\nimport pandas as pd\n\nimport ica\n\n\n# Export a transcript of the entire conversation\ndef main() -\u003e None:\n    # Allow your program to accept all the same CLI arguments as the `ica`\n    # command; you can skip calling this if have other means of specifying the\n    # contact name and output format; you can also add your own arguments this\n    # way (see the count_phrases analyzer for an example of this)\n    cli_args = ica.get_cli_parser().parse_args()\n    # Retrieve the dataframes corresponding to the processed contents of the\n    # database; dataframes include `messages` and `attachments`\n    dfs = ica.get_dataframes(\n        contact_name=cli_args.contact_name,\n        timezone=cli_args.timezone,\n        from_date=cli_args.from_date,\n        to_date=cli_args.to_date,\n        from_person=cli_args.from_person,\n    )\n    # Send the results to stdout (or to file) in the given format\n    ica.output_results(\n        pd.DataFrame(\n            {\n                \"timestamp\": dfs.messages[\"datetime\"],\n                \"is_from_me\": dfs.messages[\"is_from_me\"],\n                \"is_reaction\": dfs.messages[\"is_reaction\"],\n                # U+FFFC is the object replacement character, which appears as\n                # the textual message for every attachment\n                \"message\": dfs.messages[\"text\"].replace(\n                    r\"\\ufffc\", \"(attachment)\", regex=True\n                ),\n            }\n        ),\n        # The default format (None) corresponds to the pandas default dataframe\n        # table format\n        format=cli_args.format,\n        # When output is None (the default), ICA will print to stdout\n        output=cli_args.output,\n    )\n\n\nif __name__ == \"__main__\":\n    main()\n```\n\nYou can run the above program using the `ica` command, or execute it directly\nlike any other Python program.\n\n```sh\nica ./get_my_transcript.py -c 'Thomas Riverstone'\n```\n\n```sh\npython ./get_my_transcript.py -c 'Thomas Riverstone'\n```\n\n```sh\npython -m get_my_transcript -c 'Thomas Riverstone'\n```\n\nYou're not limited to writing a command line program, though! The\n`ica.get_dataframes()` function is the only function you will need in any\nanalyzer program. But beyond that, feel free to import other modules, send your\nresults to other processes, or whatever you need to do!\n\n### Errors and exceptions\n\n- `BaseAnalyzerException`: the base exception class for all library-related\n  errors and exceptions\n- `ContactNotFoundError`: raised if the specified contact was not found\n- `ConversationNotFoundError`: raised if the specified conversation was not\n  found\n- `FormatNotSupportedError`: raised if the specified format is not supported by\n  the library\n\n#### Using a specific timezone\n\nBy default, all dates and times are in the local timezone of the system on which\nICA is run. If you'd like to change this, you can pass the `--timezone` / `-t`\noption to the CLI with an IANA timezone name.\n\n```sh\nica totals_by_day -c 'Daniel Brightingale' -t UTC\n```\n\n```sh\nica totals_by_day -c 'Daniel Brightingale' -t America/New_York\n```\n\nThe equivalent option for the Python API is the `timezone` parameter to\n`ica.get_dataframes`:\n\n```python\ndfs = ica.get_dataframes(contact_name=my_contact_name, timezone='UTC')\n```\n\n## Developer Setup\n\nThe following instructions are written for developers who want to run the\npackage locally, or write their own analyzers.\n\n### 1. Set up virtualenv\n\n```sh\npip3 install virtualenv\n```\n\n```sh\nvirtualenv --python=python3 .virtualenv\nsource .virtualenv/bin/activate\n```\n\n### 2. Install project depdendencies\n\n```sh\npip install -r requirements.txt\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaleb531%2Fimessage-conversation-analyzer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcaleb531%2Fimessage-conversation-analyzer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaleb531%2Fimessage-conversation-analyzer/lists"}