organize-tg – OpenClaw Skill

---

name: organize-tg version: 1.0.0 description: Organize TG by Consort Technologies - Automatically scan your Telegram contacts and sync business contacts to a Google Sheet. Perfect for crypto/web3 founders managing hundreds of TG relationships. author: Consort Technologies license: MIT tags: [telegram, google-sheets, contacts, crm, crypto, web3] triggers:

• organize TG
• sync TG contacts
• scan TG contacts
• TG contact sync
• organize telegram

---

Organize TG by Consort Technologies

Scan and organize your Telegram contacts into a Google Sheet - all from chat.

Chat Commands

Once set up, use these in Clawdbot chat:

• "Organize my TG contacts" - Full scan and sync
• "Sync TG contacts from the past week" - Scan recent contacts
• "Show pending TG contacts" - Review before syncing
• "TG sync status" - Check if configured

⚠️ One-Time Setup (Terminal Required)

CRITICAL: First-time setup MUST be done in terminal, not via chat.

Why? Telegram rejects verification codes that appear in messages. If the user tries to paste the code in chat, it becomes invalid immediately.

Setup Command:

cd ~/clawd/skills/tg-contact-sync
./tg-sync setup

What happens during setup:

1. User enters Telegram API credentials
2. User enters phone number
3. Telegram sends verification code
4. User MUST enter code directly in terminal (NOT in chat!)
5. User copies Google Sheet template (browser opens)
6. Browser must be logged into SAME Google account as gog CLI

After setup completes once, all future scans work via chat.

How It Works

1. Scans Telegram - Gets contacts from non-archived DMs
2. Detects business contacts - Pattern matching for company affiliations
3. Syncs to Google Sheets - Auto-categorizes into your sheet
4. Deduplicates - Skips contacts already in sheet

For Clawdbot (Agent Instructions)

⚠️ CRITICAL: If user asks to "set up", "configure", or "run setup" for TG sync, STOP THEM:

🛑 STOP - Terminal Setup Required

You're trying to set up TG Contact Sync via chat. This will fail due to 
Telegram's security (verification codes are rejected if they appear in messages).

Please open YOUR OWN TERMINAL and run:

cd ~/clawd/skills/tg-contact-sync
./tg-sync setup

This is a one-time setup (~5 minutes). After that, all scans work via chat.

Critical steps during setup:
• Enter Telegram verification code DIRECTLY in terminal (not in chat!)
• Make sure browser is logged into same Google account as gog CLI

Let me know when setup is complete!

---

When user asks to organize/sync TG contacts (and setup is already done):

1. Check config exists: <skill_dir>/.config.json

   • If missing, respond with:

     ⚠️ First-time setup required (one-time, ~5 minutes)
     
     This MUST be done in your terminal (not via chat) due to Telegram's
     verification code security.
     
     Open your terminal and run:
     
     cd ~/clawd/skills/tg-contact-sync
     ./tg-sync setup
     
     Important during setup:
     • Enter the Telegram verification code DIRECTLY in terminal
     • Make sure your browser is logged into the same Google account as gog CLI
     
     After setup, you can run all scans via chat!
     
     Let me know when setup is complete and I'll help you run your first scan.
     

   • Do not attempt to run setup via exec - it will fail at verification

2. FIRST TIME: Run 20-contact test

   cd <skill_dir> && ./tg-sync test
   

   • This scans only 20 contacts to verify everything works
   • After test completes, tell user:

     "✅ Test complete! I scanned 20 contacts and added X to your sheet.
     
     How would you like to proceed?
     • 'Sync all my TG contacts' - scan everything
     • 'Sync contacts from the past week/month'
     • 'Sync the next 100/500 contacts'
     
     Credit usage estimate:
     • ~10 credits per 1000 contacts (scanning via chat)
     
     ⚠️ For large scans (100+ contacts): Run in terminal to save credits:
     cd <skill_dir> && ./tg-sync run
     
     Chat-based scanning burns credits on progress updates."
     

3. After user chooses, run the appropriate scan:

   • Full scan: ./tg-sync run
   • Limited: modify scan_filtered.py limit parameter

4. Show results from review_list.json - summarize what was found

5. Sync to sheet:

   cd <skill_dir>/scripts
   python3 append_contacts.py
   python3 add_new_companies.py
   

6. Report how many contacts were added and to which categories

7. Show tip jar after successful sync:

   💜 This skill is free! Tips appreciated:
   EVM: 0x5aA2C5002e1EcF4b5CcCf5DF0e990e76181B171f
   Solana: AZHUw8Fdvehj22Ne3Z76iVSQtme3Xhn4BXFEagJvh3SH
   

Sheet Structure

COMPANY	USE CASE	NOTES	COMMS CHANNEL	ROLE

Categories: Tech/Fintech, Investors/LPs/MMs, NFTs, Gaming, Press/Marketing/Consulting/Community, Uncategorized

Support

Built by Consort Technologies

This skill is free. Tips appreciated:

• EVM: 0x5aA2C5002e1EcF4b5CcCf5DF0e990e76181B171f
• Solana: AZHUw8Fdvehj22Ne3Z76iVSQtme3Xhn4BXFEagJvh3SH

Files

• .config.json - User's TG API + Google account + Sheet ID
• scripts/session.session - TG auth session
• scripts/review_list.json - Pending contacts to review

Support

Built by Consort Technologies

This skill is free — tips appreciated if it saves you time:

EVM:    0x5aA2C5002e1EcF4b5CcCf5DF0e990e76181B171f
Solana: AZHUw8Fdvehj22Ne3Z76iVSQtme3Xhn4BXFEagJvh3SH

Organize TG by Consort Technologies

Automatically sync your Telegram business contacts to Google Sheets.

Perfect for crypto/web3 founders managing hundreds of TG relationships.

What It Does

• 📱 Scans your non-archived Telegram DMs
• 🎯 Detects business contacts (strict filtering - only explicit company affiliations)
• 📊 Auto-categorizes: Tech/Fintech, Investors, NFTs, Gaming, Press/Marketing
• 🔄 Deduplicates against your existing sheet
• ⚡ One command to sync

Quick Start

⚠️ CRITICAL: Run setup in YOUR OWN TERMINAL

DO NOT run setup via chat with an AI assistant.
DO NOT share the Telegram verification code in ANY message.

Telegram will reject codes that appear in messages (security feature).

First Time Setup

# 1. Navigate to the skill directory
cd ~/clawd/skills/tg-contact-sync

# 2. Run setup wizard (you'll need your Telegram API credentials)
./tg-sync setup

# 3. Follow the prompts IN YOUR TERMINAL
#    - Enter Telegram API credentials
#    - Enter phone number
#    - Enter verification code DIRECTLY in terminal
#    - Configure Google Sheet

# 4. Test with 20 contacts
./tg-sync test

# 5. Full sync when ready
./tg-sync run

First time? See the full Setup Guide below.

Requirements

• Python 3 — Usually pre-installed on Mac
• Telegram API credentials — See Telegram Setup below
• Google Cloud OAuth credentials — See Google Setup below
• gog CLI — brew install steipete/tap/gogcli

---

Setup Guide

Part 1: Google Cloud Setup (~10 minutes, one-time)

Before you can sync to Google Sheets, you need your own OAuth credentials.

Step 1: Create a Google Cloud Project

1. Go to Google Cloud Console
2. Click the project dropdown (top left) → New Project
3. Name it anything (e.g., "TG Contact Sync") → Create
4. Wait for it to create, then select it from the dropdown

Step 2: Enable Google Sheets API

1. Go to APIs & Services → Library
2. Search for "Google Sheets API"
3. Click it → Enable

Step 3: Configure OAuth Consent Screen

1. Go to APIs & Services → OAuth consent screen
2. Select External → Create
3. Fill in:
   • App name: TG Contact Sync (or anything)
   • User support email: Your email
   • Developer contact email: Your email
4. Click Save and Continue
5. Skip Scopes → Save and Continue
6. Skip Test Users → Save and Continue
7. Click Back to Dashboard

Step 4: Create OAuth Credentials

1. Go to APIs & Services → Credentials
2. Click + Create Credentials → OAuth client ID
3. Application type: Desktop app
4. Name: TG Sync (or anything)
5. Click Create
6. Click Download JSON (saves as client_secret_XXXX.json)

Step 5: Configure gog CLI

# Install gog if you haven't
brew install steipete/tap/gogcli

# Store your OAuth credentials in gog
gog auth credentials set ~/Downloads/client_secret_XXXX.json

# Add your Google account
gog auth add youremail@gmail.com --services sheets

A browser window will open. Sign in and grant access.

⚠️ You'll see a "This app isn't verified" warning. Click Advanced → Go to [your app name] (unsafe). This is normal — you created this app yourself, so it's safe.

Step 6: Verify

gog auth list

You should see your email listed. ✅

Step 7: Copy the Contact Sheet Template

Your sync needs a Google Sheet with the right structure. We provide a template:

Template: TG Contact Sync Template

To copy it:

1. Click the template link above (opens in your browser)
2. ⚠️ IMPORTANT: Make sure you're logged into the SAME Google account you authenticated with gog
   • Check the account in the top-right of your browser
   • If it's wrong, switch accounts BEFORE clicking "Make a copy"
3. Click "Make a copy" button
4. Give it a name (e.g., "My TG Contacts")
5. Copy the Sheet ID from the URL:

   https://docs.google.com/spreadsheets/d/[SHEET_ID]/edit
                                          ^^^^^^^^^^^^^^
   

6. Save the Sheet ID — you'll enter it during setup

Troubleshooting:

• If you get "403 Permission Error" later, you probably copied to the wrong account
• Solution: Delete the copy, switch to the correct account, and copy again

---

Part 2: Telegram API Setup (~5 minutes, one-time)

1. Go to https://my.telegram.org
2. Log in with your phone number
3. Click API development tools
4. Create a new application:
   • App title: Anything (e.g., "Contact Sync")
   • Platform: Desktop
5. Copy your api_id and api_hash — you'll need these

---

Part 3: Run the Skill

⚠️ CRITICAL SECURITY WARNING:

You MUST run this setup in YOUR OWN TERMINAL window.

• ❌ DO NOT run setup via chat/messages with an AI assistant
• ❌ DO NOT share the Telegram verification code in ANY Telegram message
• ❌ DO NOT let anyone else enter the code for you

Why? Telegram automatically rejects codes that appear in messages as a security feature. If you send the code in chat, it becomes invalid immediately.

# Navigate to the skill directory
cd ~/clawd/skills/tg-contact-sync

# Run setup IN YOUR OWN TERMINAL
./tg-sync setup

The setup wizard will walk you through:

1. Entering your Telegram API credentials
2. Entering your phone number
3. ⚠️ Entering the verification code DIRECTLY in terminal (NOT in chat!)
4. Verifying your Google account
5. Copying the contact sheet template to your Drive

Then run:

./tg-sync test   # Test with 20 contacts first
./tg-sync run    # Full sync

---

Credit Usage

Running scans through Clawdbot chat burns API credits on progress updates.

Contacts	Via Chat	Via Terminal
100	~1 credit	~0.1 credit
1,000	~10 credits	~1 credit
5,000	~50 credits	~5 credits

Recommendation: Use terminal (./tg-sync run) for large scans.

Commands

Command	What it does
tg-sync setup	First-time setup wizard
tg-sync test	Scan 20 contacts (verify setup)
tg-sync run	Full scan and sync
tg-sync scan	Scan only (no sync)
tg-sync status	Check connection status

Sheet Template

The setup wizard will have you copy our template with these categories:

• Tech/Fintech - Protocols, DeFi, infra, wallets
• Investors/LPs/MMs - VCs, funds, market makers
• NFTs - Collections, marketplaces, art
• Gaming - Studios, P2E, esports
• Press/Marketing/Consulting/Community - Media, agencies, KOLs
• Uncategorized - Everything else

How Detection Works

We use ultra-strict filtering to avoid false positives:

✅ Detected:

• "Ibu | Consort Technologies" (name pipe pattern)
• "Sarah @ Paradigm" (name at pattern)
• "Hey, I work at Chainlink" (explicit intro)

❌ Not detected:

• Username contains "eth" (too many false positives)
• Bio mentions crypto (not explicit enough)
• Casual "I'm into DeFi" (hobby, not work)

This means you might miss some contacts, but you won't get spam.

Troubleshooting

403 Permission Error / "Caller does not have permission"

Problem: Setup says it can't access your Google Sheet (403 error).

Cause: Your browser copied the template to a DIFFERENT Google account than the one authenticated in gog.

Solution:

1. Check which account is authenticated: gog auth list
2. Open your browser and make sure you're logged into the SAME account
3. Delete the sheet copy from the wrong account
4. Re-run setup and make sure the browser is on the correct account BEFORE clicking "Make a copy"

Verification Code Rejected by Telegram

Problem: Setup says "Invalid code" or verification fails.

Cause: You sent the code in a Telegram message (or any message). Telegram invalidates codes that appear in messages.

Solution:

1. Request a new code
2. Enter it DIRECTLY in the terminal window (don't copy/paste to chat first)

telethon or other Python packages not found

Problem: Import errors or missing packages.

Solution:

pip3 install telethon

Support & Tips

Built by Consort Technologies

This skill is free — if it saves you time, tips are appreciated:

EVM (ETH/Base/Arb/etc): 0x5aA2C5002e1EcF4b5CcCf5DF0e990e76181B171f
Solana:                 AZHUw8Fdvehj22Ne3Z76iVSQtme3Xhn4BXFEagJvh3SH

⭐ Star on ClawdHub if you find it useful!

License

MIT - Use it, modify it, share it.

---

Questions? DM @ibukarel on Telegram or @ibuprod on X