API Scraper

The API Scraper is TeleSender's powerful member extraction tool that connects directly to Telegram's MTProto API to retrieve detailed member information from groups and channels.

Overview

Unlike web-based scrapers that rely on DOM manipulation, TeleSender's API Scraper uses Telegram's official protocol for reliable, accurate data extraction with comprehensive filtering options.

How It Works

Select Group → Configure Filters → Set Limits → Start Scraping → Export Results

The scraper operates in these phases:

1. Group Selection — Choose from your joined groups/channels
2. Configuration — Set limits, filters, and delay settings
3. Extraction — Fetch member data via Telegram API
4. Processing — Parse and structure the data
5. Storage — Save to local database and export

Getting Started

Accessing the Scraper

1. Open TeleSender Options page
2. Navigate to Campaigns tab
3. Click "New Campaign"
4. Select "Scrape Only" campaign type

Selecting a Group

Your joined groups and channels appear in a dropdown:

📁 Group Name (123 members) - @username
📢 Channel Name (5.2k members) - @channelname

tip

Groups with more members may take longer to scrape. Start with smaller groups (under 1,000 members) while learning the tool.

Configuration Options

Scrape Limit

Control how many members to extract:

Plan	Maximum Members
Demo	50
Pro	1,000
Enterprise	10,000+

// Configuration example
{
  limit: 500,  // Number of members to scrape
}

Delay Settings

Choose between two delay modes:

Random Delays (Recommended)

{
  delayType: 'random',
  minDelay: 1000,  // Minimum: 1 second
  maxDelay: 3500,  // Maximum: 3.5 seconds
}

Random delays between the min and max values make scraping patterns less predictable, improving account safety.

Fixed Delays

{
  delayType: 'fixed',
  fixedDelay: 2000,  // 2 seconds between requests
}

Use fixed delays when you need predictable operation timing.

Participant Filters

Filter which members to extract:

Filter	Description
Recent Members	Users who joined recently
Admins Only	Group/channel administrators
Bots	Include or exclude bot accounts
Kicked Users	Previously removed members
Banned Users	Members who were banned
My Contacts	Users in your contact list
Search by Name	Filter by name/username pattern

Example filter configuration:

{
  filters: {
    recent: true,
    adminsOnly: false,
    excludeBots: true,
    includeKicked: false,
    includeBanned: false,
    searchQuery: "john",  // Optional name filter
  }
}

Running a Scrape

Step-by-Step Process

1. Select your target group from the dropdown
2. Set the member limit (start small, e.g., 50-100)
3. Choose delay type (random recommended)
4. Configure filters if needed
5. Select anti-ban profile (Safe recommended)
6. Click "Start Scraping"

Progress Monitoring

During scraping, you'll see:

┌────────────────────────────────────────┐
│ Scraping: Marketing Group              │
│ ████████████░░░░░░░░ 58%               │
│                                        │
│ Progress: 290 / 500 members            │
│ Elapsed: 2m 34s                        │
│ Estimated remaining: 1m 48s            │
└────────────────────────────────────────┘

Controlling the Operation

• Pause — Temporarily halt scraping
• Resume — Continue from where you paused
• Stop — Cancel and save partial results

Extracted Data

Data Fields

Each scraped member includes:

{
  id: "123456789",           // Unique Telegram ID
  username: "john_doe",       // @username (if public)
  firstName: "John",          // First name
  lastName: "Doe",            // Last name (if available)
  phone: null,                // Phone (rarely available)
  isBot: false,               // Bot indicator
  isPremium: true,            // Premium subscriber
  source: "scraped",          // Data source
  sourceGroup: "-1001234567", // Group ID scraped from
  sourceGroupName: "Marketing Pros", // Group name
  addedAt: 1704067200000,     // Timestamp
}

Data Storage

Scraped data is stored in two locations:

1. Scrape History — Full results with metadata
2. Centralized Contacts — Merged into your contact database

// Storage keys
{
  SCRAPED_DATA: 'telesender-scraped-data',
  CONTACTS: 'centralized_contacts',
}

Viewing Scrape History

Access your past scrapes:

1. Go to Options → Contacts
2. Click "Scrape History"

Each history entry shows:

• Group name and ID
• Scrape timestamp
• Number of members extracted
• Actions: View, Export, Delete

Exporting Data

Export to Excel (XLSX)

1. Open scrape history or contacts
2. Click "Export to Excel"
3. File downloads as telesender-members-[timestamp].xlsx

Excel format includes columns:

• ID
• Username
• First Name
• Last Name
• Is Premium
• Is Bot
• Source Group

Export to JSON

1. Click "Export to JSON"
2. File downloads as telesender-members-[timestamp].json

JSON structure:

{
  "exportedAt": "2024-01-01T12:00:00.000Z",
  "totalMembers": 500,
  "source": {
    "groupId": "-1001234567890",
    "groupName": "Marketing Pros"
  },
  "members": [
    {
      "id": "123456789",
      "username": "john_doe",
      "firstName": "John",
      "lastName": "Doe",
      "isPremium": true,
      "isBot": false
    }
  ]
}

Best Practices

Account Safety

Protect Your Account

Aggressive scraping can trigger Telegram's anti-spam systems. Follow these guidelines:

1. Use Safe or Ultra Safe profiles for valuable accounts
2. Start with small limits (50-100 members)
3. Enable random delays for natural patterns
4. Scrape during off-peak hours (early morning, late night)
5. Spread scraping across multiple sessions rather than one large batch

Optimal Configuration

For most users, we recommend:

{
  limit: 200,
  delayType: 'random',
  minDelay: 2000,
  maxDelay: 4000,
  antiBanProfile: 'SAFE',
}

Rate Limiting Considerations

Telegram enforces rate limits. TeleSender handles these automatically:

Limit Type	Handling
FloodWait	Auto-pause for required duration
Channel Private	Skip with warning
Privacy Restricted	Skip user, continue

Troubleshooting

"Channel Private" Error

Problem: Cannot access the target group

Solutions:

1. Ensure you're a member of the group
2. Check if the group was deleted or made private
3. Refresh your group list

"FloodWait X seconds" Warning

Problem: Telegram rate limited your account

Solutions:

1. Wait for the specified duration
2. Switch to a slower anti-ban profile
3. Reduce scrape limits

Empty Results

Problem: Scrape completes with 0 members

Solutions:

1. Verify you selected the correct group
2. Check if the group has visible members
3. Ensure your filters aren't too restrictive
4. Some channels don't expose member lists

Slow Scraping

Problem: Scraping takes too long

Solutions:

1. This is intentional for safety
2. Use "Moderate" or "Fast" profile (at your own risk)
3. Reduce the member limit
4. Schedule scrapes during low-activity periods

Integration with Other Features

Sending to Scraped Members

1. Complete a scrape
2. Create a new "Import-Send" campaign
3. Select scraped contacts as targets
4. Compose and send your message

AI Lead Scoring

1. After scraping, go to AI → Lead Scorer
2. Select scraped contacts
3. Run AI scoring
4. Filter by score for targeted outreach

Building Campaigns

Use scraped data in campaign workflows:

Scrape → Filter by AI Score → Send Messages → Track Results

Learn about Campaign Builder →

Data Management

Clearing History

To delete scrape history:

1. Go to Contacts → Scrape History
2. Click the trash icon on individual entries
3. Or click "Clear All History"

Merging Contacts

When you scrape multiple groups:

• Contacts are automatically deduplicated by ID
• Existing contacts are updated with new data
• Source information is preserved

---

Quick Reference

Setting	Recommended	Range
Limit	200	1-10,000
Min Delay	2,000ms	500-5,000ms
Max Delay	4,000ms	1,000-10,000ms
Profile	Safe	Ultra Safe to Fast

---

Next: Learn about Bulk Sender →