Telegram Smart Member Adder

Add Telegram members from any group to your channel using multi-account rotation, AI-style filters, and automatic flood control. Pay only $0.01 per member successfully added.

Why this Actor?

Most Telegram member adder tools on the market share common problems: they require a QR code login on every run, have no flood control (getting your accounts banned), output only a visual log with no structured data, and charge a flat monthly fee regardless of how many members you actually add.

This Actor solves all of those issues:

Feature	Typical alternatives	This Actor
Auth	QR code every run	Session string (no QR, reusable)
Multi-account	Basic or none	Rotation + per-account cooldown
Flood control	Manual reset next day	Auto backoff + exponential cooldown
Member filters	None	Language, bio keywords, premium flag
Output	Visual log only	Structured JSON dataset (MCP-ready)
AI / MCP ready	No	Yes — OpenAPI + MCP configurator
Pricing	Flat monthly fee	$0.01 per member successfully added
Dry-run mode	No	Yes — test without adding anyone

How it works

1. Logs into Telegram using your pre-authorized session strings (no QR code needed).
2. Fetches members from source_chat up to max_members_to_fetch.
3. Applies optional filters (language, bio keywords, premium flag).
4. Adds filtered members to target_chat, rotating accounts automatically.
5. Writes one structured result record per attempted user to the Apify dataset.
6. Charges $0.01 per successfully added member via PAY_PER_EVENT.

Input

{
  "source_chat": "@source_group",
  "target_chat": "@target_channel",
  "accounts": ["SESSION_STRING_1", "SESSION_STRING_2"],
  "max_members_to_fetch": 500,
  "dry_run": false,
  "delay_range_seconds": { "min": 30, "max": 90 },
  "filters": {
    "language": "en",
    "bio_keywords": ["crypto", "trading"],
    "premium_only": false
  }
}

Fields

Field	Type	Required	Default	Description
source_chat	string	Yes	-	Source group username or ID
target_chat	string	Yes	-	Target channel username or ID
accounts	array	Yes	-	List of Telegram session strings
max_members_to_fetch	integer	No	500	Max members to fetch (1-10000)
dry_run	boolean	No	false	Simulate without adding anyone
delay_range_seconds	object	No	{min:30,max:90}	Random delay between adds
filters	object	No	{}	Optional member filters

Filters object

Field	Type	Description
language	string	Keep only users with this language code (e.g. en, it, es)
bio_keywords	array	Keep users whose bio contains at least one keyword
min_last_seen_days	integer	Keep only users active within last N days (1-365)
premium_only	boolean	If true, keep only Telegram Premium users

Output

One record per attempted member, pushed to the default Apify dataset:

{
  "source_chat": "@source_group",
  "target_chat": "@target_channel",
  "member_id": 123456789,
  "username": "example_user",
  "first_name": "John",
  "last_name": "Doe",
  "premium": false,
  "status": "added"
}

Possible status values:

Status	Meaning
added	Member successfully added
already_participant	User is already in the target chat
privacy_restricted	Telegram privacy settings block adding this user
chat_write_forbidden	Bot/account cannot write to target chat
skipped_floodwait	Account hit FloodWait, member skipped
dry_run	Simulated — not actually added
error:SomeError	Other Telegram error

Pricing

• Model: PAY_PER_EVENT
• Price: $0.01 per successfully added member
• Event name: member-added
• Apify free plan credits ($5/month) apply automatically — no separate subscription needed.
• You only pay for results. A run with 0 successful adds costs $0.

Environment variables

Set these in the Actor settings before running:

Variable	Description
TELEGRAM_API_ID	Your Telegram API ID from https://my.telegram.org
TELEGRAM_API_HASH	Your Telegram API hash (mark as Secret)

How to generate a session string

Run this script once locally to get a session string for each account:

from telethon.sync import TelegramClient
from telethon.sessions import StringSession

API_ID = 123456       # your API ID
API_HASH = "your_hash"

with TelegramClient(StringSession(), API_ID, API_HASH) as client:
    print(client.session.save())

The printed string goes into the accounts array. You can have multiple accounts for better rotation.

AI Agent and MCP compatibility

This Actor is fully compatible with AI agents and MCP (Model Context Protocol) workflows:

• OpenAPI definition available via the Apify API — any AI agent can discover and call this Actor automatically.
• MCP configurator available in the Actor's API menu — generate an MCP server config in one click.
• Structured JSON output — every result is a clean, typed record suitable for downstream AI processing.
• Deterministic input schema — the JSON input schema is machine-readable, so AI agents can fill it without human help.
• Callable via REST — POST https://api.apify.com/v2/acts/opportunity-biz~apify-telegram-smart-member-adder/runs with your JSON input.

Example: calling from an AI agent

import requests

response = requests.post(
    "https://api.apify.com/v2/acts/opportunity-biz~apify-telegram-smart-member-adder/run-sync-get-dataset-items",
    headers={"Authorization": "Bearer YOUR_APIFY_TOKEN"},
    json={
        "source_chat": "@my_source_group",
        "target_chat": "@my_target_channel",
        "accounts": ["SESSION_STRING"],
        "max_members_to_fetch": 100,
        "dry_run": True
    }
)
results = response.json()
print(f"{len(results)} members processed")

Best practices

• Always run with dry_run: true first to verify your setup without adding anyone.
• Use at least 2-3 accounts to distribute load and reduce flood risk.
• Keep delay_range_seconds.min at 30 or higher.
• Respect Telegram Terms of Service and applicable local privacy laws.
• Do not use on groups/channels you do not own or have explicit permission for.

Running locally

pip install -r requirements.txt
export TELEGRAM_API_ID=123456
export TELEGRAM_API_HASH=your_hash
export APIFY_TOKEN=your_token
python main.py

Create apify_storage/key_value_stores/default/INPUT.json with your input JSON before running.