tg-contacts 1.0.1
Telegram contacts JSON to Android-ready CSV/VCF converter
License: MIT
Requires Python: >=3.7
Keywords: telegram, contacts, android, csv, vcf

# 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

```bash
pip install tg-contacts
```

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


Verify installation:

```bash
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](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

```bash
tg-contacts -i result.json
```

➡ Creates a timestamped CSV file:

```
android_contacts_YYYYMMDD_HHMMSS.csv
```

---

## Output Formats

### CSV (default)

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

Best for:

* Google Contacts web import
* Spreadsheet editing

### VCF (recommended for Android/iOS)

```bash
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)

```bash
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.

```bash
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.

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

### Examples

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

```bash
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:

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

---

## Custom Output File

```bash
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](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

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

```bash
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:

```bash
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