{"id":15285667,"url":"https://github.com/starkdmi/whats_json","last_synced_at":"2026-04-29T08:07:39.192Z","repository":{"id":65529572,"uuid":"590937741","full_name":"starkdmi/whats_json","owner":"starkdmi","description":"Convert WhatsApp _chat.txt messages to JSON","archived":false,"fork":false,"pushed_at":"2024-01-27T18:54:37.000Z","size":20266,"stargazers_count":1,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-26T16:50:28.907Z","etag":null,"topics":["cli","dart","dartlang","pubdev","whatsapp","whatsapp-chat"],"latest_commit_sha":null,"homepage":"https://pub.dev/packages/whats_json","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/starkdmi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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":"2023-01-19T15:06:53.000Z","updated_at":"2024-12-05T20:17:26.000Z","dependencies_parsed_at":"2024-01-27T19:56:34.635Z","dependency_job_id":null,"html_url":"https://github.com/starkdmi/whats_json","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/starkdmi/whats_json","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starkdmi%2Fwhats_json","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starkdmi%2Fwhats_json/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starkdmi%2Fwhats_json/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starkdmi%2Fwhats_json/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/starkdmi","download_url":"https://codeload.github.com/starkdmi/whats_json/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/starkdmi%2Fwhats_json/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32416182,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T06:29:02.080Z","status":"ssl_error","status_checked_at":"2026-04-29T06:29:00.631Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["cli","dart","dartlang","pubdev","whatsapp","whatsapp-chat"],"created_at":"2024-09-30T15:07:05.107Z","updated_at":"2026-04-29T08:07:39.145Z","avatar_url":"https://github.com/starkdmi.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"# whats_json\n\u003e Dart package and cli tool for extracting messages from WhatsApp **_chat.txt** file and convert them to **JSON** format\n\n## Features\n- Supports personal and group chats, [iOS](https://faq.whatsapp.com/iphone/chats/how-to-back-up-to-icloud/) and [Android](https://faq.whatsapp.com/1180414079177245) export formats\n- Works with attachments and locations\n- Detect system messages regardless of language\n- Process dates in multiple calendars and locales\n- Crossplatform with power of [Dart](https://dart.dev/)\n\n## Command line tool\nSimple command line application provide interface to convert exported **_chat.txt** to **JSON** file. [More](https://github.com/starkdmi/whats_json/blob/main/cli/README.md)\n```Bash\ndart cli.dart -i chat.txt -o chat.json\n```\n\n## Package\nDart package support all the platforms including Web. Simply include latest version from [pub.dev](https://pub.dev/packages/whats_json) to `pubspec.yaml`\n```Dart\n// read file\nfinal stream = File(\"_chat.txt\")\n    .openRead()\n    .transform(const Utf8Decoder())\n    .transform(const LineSplitter());\n\n// get messages\nList\u003cMap\u003cString, dynamic\u003e\u003e messages = await whatsGetMessages(stream);\n```\n\n## Fields\nWhen messages are processed the following fields can appear in results\n\u003ctable\u003e\n    \u003ctr\u003e\n        \u003ctd align=\"center\"\u003e\u003cb\u003eName\u003c/b\u003e\u003c/td\u003e\n        \u003ctd align=\"center\"\u003e\u003cb\u003eRequired\u003c/b\u003e\u003c/td\u003e\n        \u003ctd align=\"center\"\u003e\u003cb\u003eValue\u003c/b\u003e\u003c/td\u003e\n        \u003ctd align=\"center\"\u003e\u003cb\u003eDescription\u003c/b\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd align=\"center\"\u003e\u003ci\u003etype\u003c/i\u003e\u003c/td\u003e\n        \u003ctd align=\"center\"\u003e\u003cb\u003erequired\u003c/b\u003e\u003c/td\u003e\n        \u003ctd align=\"center\"\u003e\u003ccode\u003etext\u003c/code\u003e, \u003ccode\u003eimage\u003c/code\u003e, \u003ccode\u003evideo\u003c/code\u003e, \u003ccode\u003eaudio\u003c/code\u003e, \u003ccode\u003egif\u003c/code\u003e, \u003ccode\u003esticker\u003c/code\u003e, \u003ccode\u003efile\u003c/code\u003e, \u003ccode\u003elocation\u003c/code\u003e, \u003ccode\u003esystem\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eMessage type, based on that field optional fields are present or absence\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd align=\"center\"\u003e\u003ci\u003etext\u003c/i\u003e\u003c/td\u003e\n        \u003ctd\u003e\u003cb\u003erequired\u003c/b\u003e for \u003ccode\u003eText\u003c/code\u003e and \u003ccode\u003eSystem\u003c/code\u003e messages, \u003cb\u003eoptional\u003c/b\u003e for \u003ccode\u003eLocation\u003c/code\u003e and \u003ccode\u003eMedia\u003c/code\u003e messages\u003c/td\u003e\n        \u003ctd align=\"center\"\u003eany \u003ccode\u003estring\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003ePlain text\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd align=\"center\"\u003e\u003ci\u003eauthor\u003c/i\u003e\u003c/td\u003e\n        \u003ctd\u003e\u003cb\u003eoptional\u003c/b\u003e for \u003ccode\u003eSystem\u003c/code\u003e messages only, \u003cb\u003erequired\u003c/b\u003e for others\u003c/td\u003e\n        \u003ctd align=\"center\"\u003eany \u003ccode\u003estring\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eSender name or phone number\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd align=\"center\"\u003e\u003ci\u003edate\u003c/i\u003e\u003c/td\u003e\n        \u003ctd\u003ewhen \u003ccode\u003edate\u003c/code\u003e is empty, \u003ccode\u003edateString\u003c/code\u003e and \u003ccode\u003etimeString\u003c/code\u003e fields will appear\u003c/td\u003e\n        \u003ctd align=\"center\"\u003epositive \u003ccode\u003eint\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eSeconds since epoch in \u003ccode\u003eUTC\u003c/code\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd align=\"center\"\u003e\u003ci\u003edateString\u003c/i\u003e\u003c/td\u003e\n        \u003ctd\u003eexists only when \u003ccode\u003edate\u003c/code\u003e is empty\u003c/td\u003e\n        \u003ctd align=\"center\"\u003eany \u003ccode\u003estring\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eOriginal date string, stored on date and time processing failure\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd align=\"center\"\u003e\u003ci\u003etimeString\u003c/i\u003e\u003c/td\u003e\n        \u003ctd\u003eexists only when \u003ccode\u003edate\u003c/code\u003e is empty\u003c/td\u003e\n        \u003ctd align=\"center\"\u003eany \u003ccode\u003estring\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eOriginal time string, stored on date and time processing failure\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd align=\"center\"\u003e\u003ci\u003euri\u003c/i\u003e\u003c/td\u003e\n        \u003ctd\u003e\u003cb\u003erequired\u003c/b\u003e for \u003ccode\u003eMedia\u003c/code\u003e messages\u003c/td\u003e\n        \u003ctd align=\"center\"\u003eany \u003ccode\u003estring\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eMedia filename\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd align=\"center\"\u003e\u003ci\u003elink\u003c/i\u003e\u003c/td\u003e\n        \u003ctd\u003e\u003cb\u003erequired\u003c/b\u003e for \u003ccode\u003eLocation\u003c/code\u003e messages\u003c/td\u003e\n        \u003ctd align=\"center\"\u003evalid https link \u003ccode\u003estring\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eGoogle Maps or Foursquare location link\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd align=\"center\"\u003e\u003ci\u003elongitude\u003c/i\u003e\u003c/td\u003e\n        \u003ctd align=\"center\"\u003e\u003cb\u003eoptional\u003c/b\u003e\u003c/td\u003e\n        \u003ctd align=\"center\"\u003evalid longitude \u003ccode\u003estring\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eLongitude value parsed from Google Maps link\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd align=\"center\"\u003e\u003ci\u003elatitude\u003c/i\u003e\u003c/td\u003e\n        \u003ctd align=\"center\"\u003e\u003cb\u003eoptional\u003c/b\u003e\u003c/td\u003e\n        \u003ctd align=\"center\"\u003evalid latitude \u003ccode\u003estring\u003c/code\u003e\u003c/td\u003e\n        \u003ctd\u003eLatitude value parsed from Google Maps link\u003c/td\u003e\n    \u003c/tr\u003e\n\u003c/table\u003e\n\n## Date Formats and Calendars\nLibrary supports simple date formats like `4/25/2022`, `25-04-2022`, `2022.04.25` as well as localized `Tuesday, 25 April 2022`.\n\nAdditionally to Gregorian the Buddhist `3/18/2565 BE` and Japanese Imperial `3/18/R4` calendars are supported.\n\nArabic right-to-left dates are also works by default ```٢٧‏/٣‏/٢٠٢٢، ٩:٥٣:٥٦ م```.\n\n## Message Types\nMessages are divided to `Text`, `Image`, `Video`, `Audio`, `GIF`, `Sticker`, `File`, `Location` and `System`\n\n### Text\nMultiline plain text messages\n\n```Text\n[3/27/22, 21:41:35] Elon Musk: Hello, Space!\n``` \nprocessed into\n```JSON\n{\n    \"type\": \"text\",\n    \"author\": \"Elon Musk\",\n    \"date\": 1648417295,\n    \"text\": \"Hello, Space!\"\n}\n```\n\n### Attachment: Image, Video, Audio, GIF, Sticker, File\nAttachments type detected based on file name first `IMG-20220327-WA0001`, then on file extension using [mime](https://pub.dev/packages/mime) package\n\n\n**iOS**\n```Text\n[3/27/22, 21:41:55] Elon Musk: \u003cattached: 00000001-PHOTO-2022-03-27-21-41-55.jpg\u003e\n```\n**Android**\n```Text\n27/03/2022, 21:41:55 - Elon Musk: IMG-20220327-WA0001.jpg (file attached)\n```\n\nWhere `attached` and `file attached` can appear in any language. For example in Czech `file attached` is `soubor byl přiložen`.\n\n**JSON**\n```JSON\n{\n    \"type\": \"image\",\n    \"author\": \"Elon Musk\",\n    \"date\": 1648417315, \n    \"uri\": \"00000001-PHOTO-2022-03-27-21-41-55.jpg\"\n}\n```\nType is lowercased - `image`, `video`, `audio`, `gif`, `sticker`, `file`.\n\n### Location\nLocation message has two formats depending on which service is used, *Google Maps* or *Foursquare*.\n\n\n**iOS**\n```Text\n[3/27/22, 21:56:45] Elon Musk: Location: https://maps.google.com/?q=51.5021456,-0.127397\n[3/27/22, 21:46:03] Elon Musk: Pimlico Gardens (London, United Kingdom): https://foursquare.com/v/4e89af95e5fa82ad4c0aa03b\n```\n**Android**\n```Text\n27/03/2022, 21:56:45 - Elon Musk: location: https://maps.google.com/?q=51.50214569326172,-0.12739796972656\n```\n\n**JSON (Google Maps)**\n```JSON\n{\n    \"type\": \"location\",\n    \"author\": \"Elon Musk\",\n    \"date\": 1648418205,\n    \"link\": \"https://maps.google.com/?q=51.5021456,-0.127397\",\n    \"longitude\": \"51.5021456\",\n    \"latitude\": \"-0.127397\"\n}\n```\n**JSON (Foursquare)**\n```JSON\n{\n    \"type\": \"location\",\n    \"author\": \"Elon Musk\",\n    \"date\": 1648417563,\n    \"link\": \"https://foursquare.com/v/4e89af95e5fa82ad4c0aa03b\",\n    \"text\": \"Pimlico Gardens (London, United Kingdom)\"\n}\n```\n\n### System\nAll system messages translated and exported in user locale. Those translations collected from original WhatsApp localizable strings for iOS and Android, for more info check out [the patterns generator](https://github.com/starkdmi/whats_json/blob/main/tool/patterns_generator/patterns_generator.dart). \n\n```Text\n[3/18/22, 14:56:01] Elon Musk: Messages and calls are end-to-end encrypted. No one outside of this chat, not even WhatsApp, can read or listen to them.\n[1/7/23, 23:32:30] Elon Musk: Your security code with Elon changed. Tap to learn more.\n```\nprocessed into\n```JSON\n{\n    \"type\": \"system\",\n    \"text\": \"Messages and calls are end-to-end encrypted. No one outside of this chat, not even WhatsApp, can read or listen to them.\",\n    \"author\": \"Elon Musk\",\n    \"date\": 1647615361\n},\n{\n    \"type\": \"system\",\n    \"text\": \"Your security code with Elon changed. Tap to learn more.\",\n    \"author\": \"Elon Musk\",\n    \"date\": 1673134350\n},\n```\nSystem messages can have no `author` field (mostly in group chats).\n\n## Chat Export\nFollow official chat export intructions for [iOS](https://faq.whatsapp.com/iphone/chats/how-to-back-up-to-icloud/) and [Android](https://faq.whatsapp.com/1180414079177245/).\n\nCurrent implementation supports most of formats from official WhatsApp applications released before `Jan 1 2023` and will be updated for future versions.\n\n## TODO\n- [ ] Improve perfomance. Unicode regex matching takes a lot of time. Usually 100 chats proceed in 2 minutes\n- [ ] Collect more data and create more tests (chat, chat with media and group chat for every language)\n- [ ] Config - allow to set less locales, date and time formats, optionally disable date processing\n\n## Why\nThere is a lot of packages on Github which parse WhatsApp _chat.txt files but many of them are too simple and do not cover every edge case. The good one is [whatsapp-chat-parser](https://github.com/Pustur/whatsapp-chat-parser) while it still do not divide messages by attachment types, do not detects text system messages and is written in Node.js, which doesn't suit my needs.\n\n## More info\n**Size** - Source code is about 100KB uncompressed, while the [patterns.dart](https://github.com/starkdmi/whats_json/blob/main/lib/src/patterns.dart) is ~75KB due to all unicode characters from every translations\n\n**Research** - Collected _chat.txt files are splitted to five categories - `ios`, `android`, `languages`, `calendars` and `all chats combined`.\n[chats_unique](https://github.com/starkdmi/whats_json/blob/main/test/data/chats_unique) directory contained more that 400 unique chats, most of them were collected on Github using search api. The files from Github are markered by file name which combines github username, repository and full file path separated by space\n\n## License\nThis project is **free** for personal use. This package was developed for commercial application and it's not allowed to use to compete with it, contact me at `starkdev@icloud.com` for business use cases.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstarkdmi%2Fwhats_json","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstarkdmi%2Fwhats_json","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstarkdmi%2Fwhats_json/lists"}