Telegram Group Inviter

Telegram Group Inviter uses an authenticated Telegram user session to attempt direct invitations into one basic group or supergroup. It processes a small, user-supplied target list and returns a status row for every deduplicated target that reaches the invitation loop.

• Authenticate with a reusable Telethon StringSession or scan a QR code during the run.
• Select the first matching group dialog with a case-insensitive title, username, or numeric-ID substring.
• Attempt one to 10 supplied usernames or resolvable numeric IDs sequentially.
• Review nine-field results for success, privacy, permission, resolution, account, and rate-limit outcomes.

Open Telegram Group Inviter, use the Apify API, or connect through MCP. Direct invitations affect real accounts and groups. Use only an account and group you administer, invite only people who expect the invitation, protect all session credentials, and comply with Telegram rules and applicable law.

Why Choose This API

This Actor provides a deliberately bounded Telegram administration workflow. Runtime accepts no more than 10 target strings, removes exact trimmed duplicates, searches the authenticated account's dialogs for a basic group or supergroup, and handles each target in sequence. It does not discover people, infer consent, join groups, create invite links, or circumvent privacy controls.

Every target processed by the invitation loop produces the same nine top-level fields: processor, processed_at, target, user_id, username, first_name, last_name, status, and error. Resolution and invitation errors are translated into 13 documented statuses instead of requiring consumers to parse every Telethon exception.

The Actor uses a Telegram user authorization, not a Bot API token. A StringSession is effectively an exported authorization credential. Telethon's session documentation warns that anyone holding it may be able to log in and act as the account. Store the input as a secret, limit who can inspect runs, rotate or revoke a session if exposed, and never paste it into support requests.

On first-time QR authentication, runtime prints the newly generated session in the run log and sends a copy to the account's Saved Messages. This makes reuse possible but also creates two sensitive surfaces. The session is not intentionally written as a separate key-value-store record, yet operators must secure the log and Telegram account themselves.

Quick Start Guide

Use a test group you control before any production workflow. Confirm that the authenticated account can invite members, select an exact-enough group substring, and begin with one person who has explicitly agreed to the test.

{
  "session": "YOUR_TELETHON_STRING_SESSION",
  "group_match": "approved onboarding test",
  "usernames": ["@consenting_test_user"]
}

If session is omitted, watch the live run log. Runtime creates a QR login three times at most, with about 30 seconds available for each attempt. Scan it through Telegram's device-linking flow. When two-step verification is enabled, provide password through the secret input.

After the run, check terminal status, Dataset item count, and all rows together. Fatal authorization or group-selection errors are caught by the main process and can leave a run with zero Dataset rows even when the process finishes. A nonzero item count means the target loop wrote results; it does not mean every target was invited successfully.

Input Parameters

Field	Type	Required	Runtime behavior
session	secret string	No	Reuses a Telethon StringSession; an empty value starts QR login.
password	secret string	No	Used when Telegram requests two-step-verification during authorization.
group_match	string	Yes	Trimmed, lowercased substring used against dialog title, username, or numeric ID.
usernames	string array	Yes	One to 10 non-empty usernames or numeric IDs; exact trimmed duplicates are removed.

Group matching stops at the first qualifying dialog returned by Telegram. A short query such as team can select the wrong group when several dialogs contain it. Prefer a distinctive full title, public username, or ID fragment, then confirm the selected title and ID in logs before trusting the result.

Targets beginning with @ have that prefix removed for lookup. Numeric-only values are converted to integers. Telegram peer IDs can require session-specific peer information, so a bare numeric ID may return resolve_failed even when an account with that ID exists. @alice and alice are not exact duplicates during input cleaning and may therefore be attempted twice after normalization.

There is no public input for delays, retries, invite links, join requests, proxy selection, group creation, or batch sizes above 10. The runtime does not pause automatically after a flood_wait row; it records the result and continues to the next target.

Output Data Schema

Field	Meaning
processor	Actor URL used as processing provenance.
processed_at	ISO 8601 UTC timestamp generated for the target result.
target	Trimmed or normalized target string.
user_id	Resolved Telegram user ID, otherwise null.
username	Resolved username without @, otherwise null.
first_name	Source-reported first name, otherwise null.
last_name	Source-reported last name, otherwise null.
status	One of the 13 runtime result codes.
error	Normalized explanation for non-success outcomes.

{
  "processor": "https://apify.com/agentx/telegram-group-inviter?fpr=aiagentapi",
  "processed_at": "2026-07-23T18:40:00+00:00",
  "target": "consenting_test_user",
  "user_id": 123456789,
  "username": "consenting_test_user",
  "first_name": "Example",
  "last_name": "Member",
  "status": "success",
  "error": null
}

The statuses are success, already_member, admin_required, permission_denied, privacy_restricted, flood_wait, peer_flood, resolve_failed, unavailable, bot_blocked, user_limit_reached, blocked, and failed. They are operational categories, not legal or consent determinations. A row can contain profile fields because the user resolved successfully even when the invitation failed.

All results are pushed in one Dataset batch after the loop. If authorization, group lookup, or group inspection fails before that point, no partial target rows exist. If the Dataset write itself fails or times out, logs may show attempts without corresponding rows.

Integration Examples

Call agentx/telegram-group-inviter only from a system that can protect account credentials. Pass secrets through the Apify input secret field or a controlled secret manager, restrict run access, and retain the run ID for reconciliation.

{
  "method": "POST",
  "url": "https://api.apify.com/v2/acts/agentx~telegram-group-inviter/runs?waitForFinish=120",
  "headers": {
    "Authorization": "Bearer YOUR_APIFY_TOKEN",
    "Content-Type": "application/json"
  },
  "body": {
    "session": "YOUR_TELETHON_STRING_SESSION",
    "group_match": "approved onboarding test",
    "usernames": ["@consenting_test_user"]
  }
}

Fetch items from defaultDatasetId only after completion. Require the returned row count to equal the deduplicated target count before declaring the operation fully observed. Route success and already_member separately; neither should be blindly retried. Apply manual review and a conservative delay policy before any retry of permission, privacy, resolution, or rate-limit failures.

An MCP-capable client can fetch current Actor details and run the Actor when its plan permits. Because this operation changes external group membership, do not let an autonomous client invent targets or select a group without a prior approved input record.

Pricing & Cost Calculator

The current pay-per-event schedule defines one Actor Start event at $0.05 per run. There is no declared per-target or per-success Result event in that active schedule. A run with one target and a run with 10 targets therefore both start at $0.05; ten separate runs start at $0.50.

The charge is for starting the run, not for a successful invitation. Invalid sessions, missed QR windows, unmatched groups, zero-row outcomes, privacy restrictions, and rate limits can still incur the start event. Apify's active pricing shown at execution is authoritative if it differs from a cached Store page or this document.

Use maxTotalChargeUsd as a budget control, but do not treat it as an operational safety control. It does not verify consent, group identity, account permissions, or Telegram rate limits.

Use Cases & Applications

The suitable use case is small, consented onboarding for a group the operator administers. Examples include adding employees to an internal group after an approved access request, moving opted-in members between official community groups, or processing a short event cohort whose invitation expectation is documented.

The Dataset can support an audit trail: retain the approved source request, exact group identifier, target list, run ID, row statuses, operator, and follow-up decision. Do not use resolved names or IDs for unrelated profiling, enrichment, contact discovery, or model training.

This Actor is not appropriate for growth hacking, cold outreach, scraped member migration, competitive-community targeting, or repeated retries against privacy and anti-spam controls. Telethon's own chat documentation warns that mass-adding users may fail and can put the account and group at risk of spam restrictions.

FAQ

Do I have to be a group administrator? The runtime does not pre-certify a role. Telegram decides whether the authenticated account can invite, and failures may become admin_required or permission_denied.

Does numeric ID input always work? No. Telegram peer resolution can depend on access information known to the session. Prefer a valid username when available.

Why did the wrong group get selected? Matching is substring-based and stops at the first qualifying dialog. Use a more distinctive query and verify the logged group.

Why is the run finished with zero rows? Login, QR, session, group lookup, or group inspection may have failed before the target loop. Read logs and do not infer that the invite list was processed.

Does flood_wait make the Actor wait? No. It records Telegram's requested wait duration in error and continues. Stop further runs and respect the restriction.

Can I reuse the generated session? Yes, but anyone with the StringSession may be able to control the account. Secure logs and Saved Messages, revoke exposed sessions, and use a dedicated authorized account.

Trust & Certifications

The trust boundary is explicit: the Actor exposes its four inputs, nine output fields, 13 status codes, first-match group behavior, 10-target cap, session handling, zero-row failure path, and start-event pricing. It does not claim platform partnership, guaranteed invitations, spam immunity, legal compliance, or certification by Telegram, Telethon, Apify, a privacy authority, or a security auditor.

Telegram remains the source of truth for group state, permissions, privacy settings, peer resolution, and anti-abuse decisions. Review the official direct-invite behavior, privacy settings, and API errors when interpreting outcomes.

Legal & Compliance

Use the Telegram API only with the account owner's knowledge and authorization. Telegram's API terms require careful privacy protection and prohibit acting for users without their knowledge and consent. Invite only expected recipients and provide an appropriate process for removal or support.

Minimize stored personal data, restrict access, define retention, and document a lawful basis where required. A username or public profile does not establish consent to be added to a group. Do not evade blocks, privacy settings, rate limits, platform enforcement, or group governance. This documentation is operational guidance, not legal advice.

Related Tools

• Telegram Member Scraper — inspect authorized member data separately; never treat scraped membership as invitation consent.
• Telegram Info Scraper — retrieve public Telegram entity observations.
• Telegram Private Group Scraper — process a private group only with authorized session access.
• Telegram Chat Scraper — collect authorized chat observations without using this invite operation.
• Subreddit Member Scraper — a separate community-data workflow, not a source of implied Telegram consent.
• Twitter Info Scraper — retrieve public X profile observations in a separate pipeline.

Support & Community

For support, provide the run ID, UTC time, build number, terminal status, Dataset item count, redacted group query, number of targets, and status distribution. Do not provide the StringSession, password, QR code, API token, personal target list, or unredacted logs.

Contact AgentX support. For session security, read the official Telethon session documentation; for basic-group and supergroup invite methods, read Telethon chats and channels. Last updated: July 23, 2026.