# Telegram Group Inviter (`agentx/telegram-group-inviter`) Actor

Authenticated Telegram group invite automation. Sign in with QR or a reusable session, select a group you administer, and invite up to 10 users by username or numeric ID with per-target statuses such as success, already\_member, privacy\_restricted, and peer\_flood.

- **URL**: https://apify.com/agentx/telegram-group-inviter.md
- **Developed by:** [AgentX](https://apify.com/agentx) (community)
- **Categories:** Social media, Automation, Agents
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.05 / actor start

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

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](https://console.apify.com/actors/XI6EIILM3IjhI2X0W/input), use the [Apify API](https://docs.apify.com/api/v2), or connect through [MCP](https://docs.apify.com/integrations/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.

```json
{
  "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. |

```json
{
  "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.

```json
{
  "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](https://core.telegram.org/api/invites), [privacy settings](https://core.telegram.org/api/privacy), and [API errors](https://core.telegram.org/api/errors) when interpreting outcomes.

### Legal & Compliance

Use the Telegram API only with the account owner's knowledge and authorization. Telegram's [API terms](https://core.telegram.org/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](https://apify.com/agentx/telegram-member-scraper?fpr=aiagentapi) — inspect authorized member data separately; never treat scraped membership as invitation consent.
- [Telegram Info Scraper](https://apify.com/agentx/telegram-info-scraper?fpr=aiagentapi) — retrieve public Telegram entity observations.
- [Telegram Private Group Scraper](https://apify.com/agentx/telegram-private-group-scraper?fpr=aiagentapi) — process a private group only with authorized session access.
- [Telegram Chat Scraper](https://apify.com/agentx/telegram-chat-scraper?fpr=aiagentapi) — collect authorized chat observations without using this invite operation.
- [Subreddit Member Scraper](https://apify.com/agentx/subreddit-member-scraper?fpr=aiagentapi) — a separate community-data workflow, not a source of implied Telegram consent.
- [Twitter Info Scraper](https://apify.com/agentx/twitter-info-scraper?fpr=aiagentapi) — 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](https://t.me/AiAgentApi). For session security, read the official [Telethon session documentation](https://docs.telethon.dev/en/stable/concepts/sessions.html); for basic-group and supergroup invite methods, read [Telethon chats and channels](https://docs.telethon.dev/en/stable/examples/chats-and-channels.html). Last updated: July 23, 2026.

# Actor input Schema

## `session` (type: `string`):

Optional Telethon StringSession for a Telegram user account. Anyone holding it may be able to act as that account. If omitted, QR login is attempted in the run log and the new session is printed there and sent to Saved Messages.

## `password` (type: `string`):

Optional Telegram two-step-verification password used during authorization. It does not replace the session and is not needed for accounts without two-step verification.

## `group_match` (type: `string`):

Non-empty case-insensitive substring compared with each dialog's group title, username, or numeric ID. The first matching basic group or supergroup is selected; verify that it is the intended group and that the account can invite members.

## `usernames` (type: `array`):

One to 10 non-empty Telegram usernames (with or without @) or numeric IDs. Exact trimmed duplicates are removed; numeric IDs can still fail when the session cannot resolve the peer.

## Actor input object example

```json
{
  "group_match": "my_group",
  "usernames": [
    "@username1",
    "123456789"
  ]
}
```

# Actor output Schema

## `results` (type: `string`):

Open per-target invite results. Fatal login or group-selection errors can finish with zero rows, so verify the Dataset item count rather than terminal status alone.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "group_match": "my_group",
    "usernames": [
        "@username1",
        "123456789"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("agentx/telegram-group-inviter").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "group_match": "my_group",
    "usernames": [
        "@username1",
        "123456789",
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("agentx/telegram-group-inviter").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "group_match": "my_group",
  "usernames": [
    "@username1",
    "123456789"
  ]
}' |
apify call agentx/telegram-group-inviter --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=agentx/telegram-group-inviter",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/XI6EIILM3IjhI2X0W/builds/ddp2v1nLdXUIdRZ7V/openapi.json