tg-contacts

tg-contacts is a command-line tool that converts Telegram contact exports (JSON) into Android-ready CSV or VCF files.

It cleans, normalizes, deduplicates, and formats phone numbers so they import cleanly into Google Contacts / Android.

---

Key Features

• Supports Telegram JSON exports

• Output formats:

  • CSV (Google Contacts compatible)
  • VCF / vCard 3.0 (Android-preferred)

• Phone number normalization:

  • 00XXXXXXXX → +XXXXXXXX
  • Local → international via country code

• Country-aware formatting (--country KE)

• Deduplication by phone number

• Flexible name output modes

• Colored CLI output (optional)

• Progress bar for large exports

• Beautiful summary statistics

• Zero external dependencies

---

📥 Installation

pip install tg-contacts

⚠️ Note: Version 1.0.0 had a packaging issue. Please use 1.0.1 or newer.

Verify installation:

tg-contacts --help

---

📤 Getting Your Contacts from Telegram

You must first export your contacts using Telegram Desktop.

Step-by-step: Export contacts from Telegram

1. Install Telegram Desktop

   • Download from: https://desktop.telegram.org

2. Open Telegram Desktop

3. Navigate to:

   Settings → Advanced → Export Telegram Data
   

4. In the export window:

   • Check Contacts list
   • Uncheck everything else

5. Choose JSON (recommended) or HTML

6. Click Export

7. After export completes:

   • Locate the exported folder

   • Find a file similar to:

     result.json
     

This JSON file is your input for tg-contacts.

---

Basic Usage

tg-contacts -i result.json

➡ Creates a timestamped CSV file:

android_contacts_YYYYMMDD_HHMMSS.csv

---

Output Formats

CSV (default)

tg-contacts -i result.json --format csv

Best for:

• Google Contacts web import
• Spreadsheet editing

VCF (recommended for Android/iOS)

tg-contacts -i result.json --format vcf

Best for:

• Direct Android or iOS imports
• Preserving contact metadata

---

Country-Based Phone Normalization

Automatically converts local numbers into international format.

Example (Kenya)

tg-contacts -i result.json --country KE

Input	Output
0701234567	+254701234567
701234567	+254701234567
00254701234567	+254701234567

Currently supported:

• KE (Kenya)

(More countries can be added, I focused on my use case.)

---

Deduplication

Remove duplicate contacts based on phone number.

tg-contacts -i result.json --dedupe phone

• Keeps the first occurrence
• Reports number of duplicates removed

---

Name Output Modes

Control which name fields are included.

--name-mode both   # Default
--name-mode first
--name-mode last

Examples

tg-contacts -i result.json --name-mode first

tg-contacts -i result.json --name-mode last

---

Colored Output

Colored output is enabled by default.

Disable it if piping output or on unsupported terminals:

tg-contacts -i result.json --no-color

---

Custom Output File

tg-contacts -i result.json -o my_contacts.vcf

If omitted, a timestamped filename is generated automatically.

---

Final Summary Statistics

At the end of every run, you’ll see:

• Total input contacts
• Written contacts
• Duplicates removed
• Numbers normalized (00 → +)
• Numbers normalized via country
• Output format
• Output file path

Example:

[+] Summary
• Input contacts        : 512
• Written contacts      : 487
• Duplicates removed    : 25
• 00 → + normalized     : 38
• Country normalized    : 412
• [-] Output format         : VCF

---

Importing into Android

Option 1: Google Contacts (recommended)

1. Go to https://contacts.google.com
2. Click Import
3. Upload the generated CSV or VCF
4. Sync your phone

Option 2: Direct phone import (VCF)

1. Copy .vcf file to phone
2. Open it
3. Import into Contacts

---

Example Power Commands

tg-contacts -i result.json --country KE --dedupe phone --format vcf

tg-contacts -i result.json --name-mode first --format csv

---

Privacy & Security

• All processing is local
• No network calls
• No data leaves your machine
• Safe for sensitive contact lists

---

Development

Clone and run locally:

git clone https://github.com/yournamejohntroony/tg-contacts
cd tg-contacts
pip install -e .

---

License

MIT License

---

Roadmap

• More country codes
• Auto country detection
• Interactive mode
• GUI version
• Homebrew & Windows builds