Telegram Export Intelligence

Turn Telegram message records you own or are authorized to process into per-post reach context, evidence, priority, and human-review actions—without scraping Telegram.

Built for: channel owners, editorial teams, agencies, community operators, marketing analysts, and evidence-governance teams working with an authorized Telegram Desktop export or internal message archive.

Commercial result unit: one delivered Telegram post intelligence row. The automatic Apify Actor start event is separate. Invalid records, duplicate records, legacy channel handles, and other diagnostics do not intentionally emit the result-found event.

This Actor is deliberately not a Telegram scraper. It does not open t.me, log into an account, use Telethon, call the Bot API, follow recorded links, read a public channel, or publish anything. You submit bounded message records from a source you are entitled to use. The Actor validates them, deduplicates them by channel and post identity, calculates transparent context from supplied metrics, and creates a review-oriented Dataset row for each valid unique message.

The distinction matters. Public visibility does not itself prove a right to commercialize somebody else's content. A Telegram handle is not an authorization token. A URL is not a licence. The product therefore places the source decision with the buyer and makes that decision explicit in the Input contract. It helps an authorized operator analyze its own records; it does not acquire records on the operator's behalf.

What you get

Each valid unique message record can produce one Dataset row with:

• a stable identity derived from normalized channel plus post ID;
• legacy-compatible channel, channelTitle, subscribers, postId, views, date, text, found, and scrapedAt fields;
• normalized numeric metrics for views, subscribers, forwards, replies, reactions, and views divided by subscribers when both inputs are available;
• an observation time that states when the Actor processed the supplied record;
• freshness calculated from the buyer-supplied message date;
• an explicit change state of not_measured because one export snapshot is not a historical baseline;
• confidence level, basis, and concrete gaps instead of a vague score;
• evidence digests that bind the normalized message record and the authorized request;
• deterministic HIGH, MEDIUM, or LOW review priority;
• a recommended next review action;
• safeToAutomate:false on every business and diagnostic row;
• failure diagnostics on non-result rows;
• settlement-neutral billing intent, with actual delivery and payment facts kept in current-run KVS OUTPUT.

The Actor also writes a terminal OUTPUT record in the default Key-Value Store. That record is the current-run operational receipt. It reconciles input counts, duplicate and invalid records, attempted processing, successful and failed work, Dataset delivery, paid and free rows, withheld work, unknown delivery or settlement, partial completion, budget stop, fatal error, exact named-event movement, and replay safety.

What you get is a compact evidence layer between an authorized archive and a human editorial or analytical decision. It is useful because the same transparent rules apply to every record. It is bounded because the Actor neither collects the archive nor claims to understand the business meaning of the content.

What the Actor intentionally does not give you

It does not provide:

• live Telegram monitoring;
• arbitrary public-channel collection;
• historical messages that are absent from your input;
• verification that a supplied channel, post, metric, title, or URL is genuine;
• verification that the buyer owns or controls the channel;
• verification that a content licence, privacy notice, consent, or contract is sufficient;
• engagement quality, audience quality, unique viewers, reach, impressions, clicks, conversions, or revenue;
• semantic sentiment, topic classification, factual accuracy, authorship, or copyright clearance;
• causal claims about why a post received its supplied number of views;
• competitor surveillance, sensitive-person profiling, political profiling, health profiling, or identity inference;
• autonomous reposting, scheduling, moderation, outreach, CRM writes, or publishing.

safeToAutomate:false is not decorative copy. It is part of the row contract. A human remains responsible for reviewing source rights, business context, content meaning, metric definitions, sensitive-data handling, and the consequences of any downstream action.

Who uses it

Channel owners

A channel owner can export a bounded set of messages, attach the subscriber snapshot used by its own reporting process, and receive a consistent table for editorial review. The output helps answer operational questions such as: Which recent records have enough supplied context to review now? Which records lack subscriber or reaction data? Which records are stale? Which records should remain baseline evidence instead of triggering a content decision?

Editorial and community teams

Editors can use the priority and evidence gaps as a triage layer before a meeting. The Actor does not decide what to publish. It helps the meeting start from a normalized set of records rather than a collection of screenshots and copied cells. A HIGH priority means the supplied record is fresh and its views-to-subscribers ratio met the deterministic rule; it does not mean the content is good, truthful, safe, or suitable to repeat.

Agencies with client authorization

An agency may process a client's export only when its contract and instructions permit that processing and delivery. The agency should keep client boundaries separate: one run per authorized purpose, no cross-client commingling, appropriate Apify access control, and deletion when the purpose ends. The authorization confirmation in Input records the buyer's attestation; it does not replace the underlying agreement.

Marketing and analytics operations

Operations teams can connect the Dataset to a spreadsheet, warehouse, dashboard, or review queue. The stable ID supports controlled joins. The input and request digests support evidence traceability. The OUTPUT receipt supports run monitoring. None of those technical properties turns the source into independently verified data.

Evidence-governance and compliance reviewers

Reviewers can inspect what the Actor received, how it normalized identity, which fields were absent, what it calculated, what it did not calculate, and whether the current run delivered and settled rows exactly. This is useful for a controlled processing record. It is not a legal conclusion and not a substitute for counsel or a data-protection assessment.

Poor-fit users

Do not use this Actor if the real requirement is to scrape channels you do not control, bypass Telegram access controls, monitor private groups, recover deleted messages, infer sensitive traits, build a people database, send unsolicited outreach, or automate publishing. Use an authorized source and a product whose rights, privacy, and access model fits that job.

How to run

1. Export or prepare authorized records

Telegram Desktop can export chat data as machine-readable JSON for an account that has legitimate access. Channel owners may also have an internal archive or an authorized feed. Prepare only the messages required for the approved analytical purpose. Remove personal details, credentials, access tokens, private invite links, confidential notes, and unnecessary free text before submission.

The Actor accepts export-style objects. A record needs:

• id or postId;
• date or a valid date_unixtime;
• a channel either on the record or at the top level;
• optional text, views, subscribers, forwards, replies, reactions, and recorded Telegram sourceUrl.

2. Confirm rights explicitly

Set authorization to the exact value:

I confirm I am authorized to process and deliver these records

The Actor refuses deliverable message records without this confirmation. The confirmation is a buyer attestation, not independent verification. Keep the underlying permission, source documentation, collection notice, contract, licence, and deletion policy in your own system.

3. Submit a bounded run

Use Apify Console, API, an Apify Task, a scheduled Task, or an authorized agent workflow. The maximum is 100 records per run. Start with two records. Confirm that Dataset and KVS OUTPUT match your integration before increasing the batch.

{
  "schemaVersion": "2.0",
  "authorization": "I confirm I am authorized to process and deliver these records",
  "sourceContext": "telegram_desktop_export",
  "channel": "my_owned_channel",
  "channelTitle": "My owned channel",
  "subscribers": 10000,
  "messages": [
    {
      "id": 101,
      "date": "2026-08-12T12:00:00Z",
      "text": "Product update for our subscribers",
      "views": 4200,
      "forwards": 31,
      "reactions": 86
    },
    {
      "id": 102,
      "date": "2026-08-11T12:00:00Z",
      "text": "Customer question and answer",
      "views": 2800,
      "forwards": 12,
      "reactions": 44
    }
  ]
}

4. Read Dataset and OUTPUT together

The Dataset contains result candidates and free diagnostics. Each business row says only that it was billing-eligible and intended for a linked result-found push. The row cannot know its final settlement because it is constructed before the platform operation completes.

Read KVS OUTPUT for current-run truth:

• run.deliveredRowCount — confirmed Dataset writes;
• run.paidRowCount — named-event deltas proven as paid;
• run.freeRowCount — confirmed free writes;
• run.withheldRowCount — valid rows not attempted after a stop;
• run.unknownDeliveryCount — a push threw and Dataset delivery is unknown;
• run.unknownSettlementCount — the Dataset write returned but named-event settlement could not be read;
• run.replaySafe — whether the failed current operation can safely be retried automatically.

5. Review before action

Sort by priority, then read recommendedAction, confidence.gaps, freshness, metrics, and the original authorized record. Do not automate publishing or consequential decisions from a priority value. If the record is incomplete, collect a better authorized export. If the record is sensitive, apply the approved privacy and retention process before any further use.

Pricing

Pricing is PAY_PER_EVENT with two separate events:

1. apify-actor-start is the automatic run-start charge.
2. result-found is charged once for one delivered Telegram post intelligence row when the exact named-event counter increases by one.

The current six-tier prices are:

Tier	Actor start	Delivered Telegram post intelligence row
FREE	$0.00500	$0.00200
BRONZE	$0.00475	$0.00190
SILVER	$0.00450	$0.00180
GOLD	$0.00425	$0.00170
PLATINUM	$0.00410	$0.00164
DIAMOND	$0.00400	$0.00160

Prices shown by Apify for the buyer's account and tier are authoritative. The table states the current approved pricing contract and must be rechecked if the Store pricing changes.

What is and is not a paid result

A paid result is one unique valid authorized message record successfully written through the linked result-found Dataset operation and reconciled by an exact named-event +1 delta.

The following do not intentionally emit result-found:

• invalid message records;
• duplicate channel/post identities;
• legacy string channel handles;
• rights-confirmation failures;
• pricing failures before delivery;
• valid rows withheld before a push because the buyer's cap cannot fund another unit;
• free migration or validation diagnostics.

The default Dataset item event must remain unpriced. The runtime checks the exact pricing event map and approved six-tier values before paid work. If the map, numeric types, tier prices, start-spend state, or result counter is unreadable or contradictory, the run fails closed rather than delivering paid work under an unknown contract.

Budget behavior

The Actor processes paid rows serially. Before each linked push it checks whether the buyer's maximum charge can cover the next result. A finite insufficient cap stops before that row. Remaining valid rows become withheld work in OUTPUT; they are not silently delivered for free.

No cap means Infinity, which is handled as a legitimate unlimited cap rather than a pricing error. A malformed cap or spend amount is a pricing error. The current result counter must start at zero for the run. Each successful paid row must move the named counter from n to n+1.

Ambiguous delivery is not ordinary budget exhaustion

If the linked Dataset push throws, the runtime does not know whether the platform accepted the row. It records unknown_delivery, marks replaySafe:false, fails the run, and never retries that row. If the push returns but the after-counter cannot be read, Dataset delivery is known while settlement is unknown; the runtime records unknownSettlementCount, fails, and does not retry. A human should inspect the run, Dataset, and platform counters before any new run.

Every new run also incurs a new start event. replaySafe:true means only that no result push was attempted in the failed current run; it does not make a new run free.

Input contract

The public schema is a first gate. Runtime normalization is normative and fail-closed.

Top-level fields

Field	Required	Meaning
schemaVersion	recommended	Must be 2.0 when present.
authorization	required for message delivery	Exact rights confirmation.
sourceContext	optional	Buyer-attested source category.
channel	required unless every message supplies it	Default handle; no URL is fetched.
channelTitle	optional	Default buyer-supplied title.
subscribers	optional	Default non-negative subscriber snapshot.
maxConcurrency	legacy	Accepted in the old 1–50 range and ignored; paid operations are intentionally serial.
messages	one of messages or items	Up to 100 export-style records.
items	legacy/additive	Message objects are processed; strings receive a migration diagnostic.

Message fields

Field	Contract
id / postId	At least one required; integer or bounded string.
channel	Optional if a valid top-level channel exists.
channelTitle	Optional buyer-supplied label, maximum 200 characters.
date	Valid date-time string.
date_unixtime	Accepted export alternative when it converts to a valid time.
text	String or Telegram export text-part array; flattened and capped at 4,000 characters.
views	Optional non-negative safe integer.
subscribers	Optional non-negative safe integer.
forwards	Optional non-negative safe integer.
replies	Optional non-negative safe integer.
reactions	Optional non-negative safe integer.
sourceUrl	Optional recorded Telegram HTTPS message URL. It must match the normalized row channel and post ID; it is never fetched.

Unknown message properties are ignored by normalization. Do not use that as an extension mechanism. If a field matters downstream, add it to a versioned contract and tests rather than relying on accidental pass-through.

Identity and duplicate rules

The uniqueness key is normalized lowercase channel plus post ID. My_Channel:101, @my_channel:101, and https://t.me/my_channel/101 context normalize to the same channel/post identity when provided in the supported fields. The first valid occurrence is retained. Later duplicates are counted and produce no row and no result event.

stableId is a SHA-256 digest of the normalized channel/post identity. It is suitable for deterministic joins. It is not an anonymization guarantee. A stable hash can remain personal data or confidential business data when it is linkable to source records.

Legacy input behavior

Versions before this reactivation accepted items:["channel"] and fetched t.me/s/<channel>. That network behavior is intentionally removed. Legacy string handles remain schema-compatible but are never fetched. A run containing only legacy handles writes one free diagnostic explaining the migration path and finishes PARTIAL with replaySafe:true because no paid push was attempted.

To migrate, export messages from an account or system authorized for the required channel and submit message objects in messages or items. This is a safer compatibility policy than silently changing a handle into an unauthorized network request.

Happy, partial, and failure output

Happy Dataset row

The following projection is derived from the local contract fixture. It demonstrates shape and deterministic values; it is not presented as a production canary receipt.

{
  "schemaVersion": "2.0.0",
  "recordType": "telegram_export_post_intelligence",
  "stableId": "sha256:3d846cbdb5965a970f46be8b8c8dcfb5073183f94862f26110ea46e2f2f406ee",
  "channel": "my_owned_channel",
  "channelTitle": "My owned channel",
  "subscribers": "10000",
  "postId": "101",
  "views": "4200",
  "date": "2026-08-12T12:00:00.000Z",
  "text": "Product update for our subscribers",
  "found": true,
  "metrics": {
    "views": 4200,
    "subscribers": 10000,
    "forwards": 31,
    "replies": null,
    "reactions": 86,
    "attentionRate": 0.42
  },
  "priority": "MEDIUM",
  "safeToAutomate": false,
  "billing": {
    "billingEligible": true,
    "billingIntent": "linked_push_result_found",
    "eventName": "result-found",
    "unit": "one delivered Telegram export post intelligence row",
    "settlementSource": "current_run_kvs_output"
  }
}

Happy current-run OUTPUT

This local acceptance projection proves the closed receipt shape used by tests. buildId and runId are explicit local-fixture identifiers, not claims about Apify production. They will be replaced in this README by the accepted immutable build and sole canary run during the remote release stage.

{
  "buildId": "local-acceptance-pending-remote",
  "runId": "local-test-telegram-export-run",
  "status": "SUCCEEDED",
  "evidenceAccepted": true,
  "proofScope": "local_contract_fixture",
  "actorStatus": "COMPLETE",
  "input": {
    "requestedCount": 2,
    "uniqueCount": 2,
    "duplicateCount": 0,
    "invalidCount": 0,
    "legacyChannelCount": 0
  },
  "run": {
    "attemptedCount": 2,
    "successfulCount": 2,
    "failedCount": 0,
    "deliveredRowCount": 2,
    "paidRowCount": 2,
    "freeRowCount": 0,
    "withheldRowCount": 0,
    "unknownDeliveryCount": 0,
    "unknownSettlementCount": 0,
    "partial": false,
    "budgetStopped": false,
    "fatalError": null,
    "replaySafe": false,
    "safeToAutomate": false
  },
  "delivery": {
    "eventName": "result-found",
    "attemptedPushCount": 2,
    "resultChargeCountBefore": 0,
    "resultChargeCountAfter": 2,
    "confirmedEventDelta": 2,
    "confirmedDatasetWrites": 2
  }
}

Partial legacy migration output

{
  "buildId": "local-acceptance-pending-remote",
  "runId": "local-test-telegram-export-run",
  "status": "SUCCEEDED",
  "evidenceAccepted": true,
  "proofScope": "local_contract_fixture",
  "actorStatus": "PARTIAL",
  "diagnostic": {
    "recordType": "telegram_export_processing_diagnostic",
    "found": false,
    "summary": "1 legacy channel handle(s) were not fetched. This version processes owner-authorized message exports only.",
    "recommendedAction": "Export messages you own or are authorized to process, then submit them in the messages field.",
    "billingEligible": false
  },
  "run": {
    "deliveredRowCount": 1,
    "paidRowCount": 0,
    "freeRowCount": 1,
    "withheldRowCount": 0,
    "partial": true,
    "fatalError": null,
    "replaySafe": true
  }
}

Failure output

Failures before a result push—for example missing rights confirmation, missing current hosted run identity, or invalid pricing—write a failed OUTPUT receipt when KVS is available, call Actor.fail, and keep replaySafe:true. Failures after a result push use replaySafe:false because a new run could duplicate a delivered or charged row.

An unknown-delivery projection contains:

{
  "status": "FAILED",
  "run": {
    "deliveredRowCount": 0,
    "paidRowCount": 0,
    "unknownDeliveryCount": 1,
    "unknownSettlementCount": 0,
    "fatalError": "unknown_delivery",
    "replaySafe": false
  },
  "delivery": {
    "attemptedPushCount": 1,
    "confirmedDatasetWrites": 0,
    "lastAttempt": {
      "state": "unknown_delivery",
      "resultChargeCountBefore": 0,
      "resultChargeCountAfter": null,
      "delta": null
    }
  }
}

Do not blind-retry that run. Inspect the Dataset and charged event counters first. A settlement-unknown failure differs: confirmedDatasetWrites and deliveredRowCount include the returned Dataset write, while unknownSettlementCount records that payment could not be classified.

Field dictionary

Legacy-compatible identity and content fields

Field	Meaning
input	Normalized channel copied for backward-compatible integrations.
channel	Normalized buyer-supplied channel handle.
channelTitle	Buyer-supplied title or null.
subscribers	Supplied subscriber count rendered as a legacy string or null.
postId	Supplied normalized post identity.
views	Supplied views rendered as a legacy string or null.
date	Normalized message date.
text	Flattened message text, maximum 4,000 characters.
found	true for a business result candidate; false for a diagnostic.
scrapedAt	Legacy field now equal to processing time. It no longer means a scrape occurred.

The legacy field name scrapedAt is retained only for backward compatibility. New integrations should use processedAt or observedAt.

Contract and evidence fields

Field	Meaning
schemaVersion	Dataset contract version 2.0.0.
recordType	Business intelligence row or processing diagnostic.
stableId	Digest of normalized channel plus post ID.
processedAt	When the Actor normalized the record.
sourceUrl	Recorded same-channel, same-post Telegram HTTPS URL, never fetched or verified.
requestDigest	Digest of the normalized authorized request.
inputDigest	Digest of the normalized message or null for a diagnostic.
evidence	Typed digest references to the message record and rights attestation.

Metrics

Field	Meaning and limit
metrics.views	Buyer-supplied count, not live-verified.
metrics.subscribers	Buyer-supplied snapshot, not live-verified.
metrics.forwards	Buyer-supplied count or null.
metrics.replies	Buyer-supplied count or null.
metrics.reactions	Buyer-supplied count or null.
metrics.attentionRate	views / subscribers rounded to six decimals when both values support it.

attentionRate is not unique reach, engagement rate, conversion rate, or audience quality. Telegram metrics can change after export. The subscriber snapshot may represent a different time from the message's view count. Use the value only as a supplied-snapshot review signal.

Decision fields

Field	Meaning
observedAt	Processing time of this authorized snapshot.
freshness.status	fresh at no more than 7 days, aging through 30 days, otherwise stale.
freshness.ageSeconds	Non-negative age from message date to processing time.
freshness.basis	Always states the buyer-supplied date basis.
change.status	not_measured; this Actor has no cross-run baseline.
confidence.level	Completeness-oriented HIGH, MEDIUM, or LOW.
confidence.basis	Validation and identity facts the Actor can prove.
confidence.gaps	Missing supplied fields and unverified-source limitations.
recommendedAction	Deterministic human review route.
priority	Deterministic HIGH, MEDIUM, or LOW review order.
safeToAutomate	Always false.
summary	Concise evidence-bounded statement.

Failure and billing fields

Field	Meaning
failureDiagnostics	Structured type, retryability, and stage for diagnostics; null for a normal result.
billing.billingEligible	Whether the row was a candidate for linked paid delivery.
billing.billingIntent	Linked paid push or free diagnostic write.
billing.eventName	result-found for a business candidate, otherwise null.
billing.unit	Human-readable unit definition.
billing.settlementSource	Always current_run_kvs_output.

Never use billingEligible:true as proof of payment. Use OUTPUT.run.paidRowCount, the named counter transition, and platform charged-event evidence from the same run.

Evidence and boundaries

Evidence the Actor can prove

The Actor can prove that:

• input satisfied its closed normalization rules;
• the exact authorization confirmation string was present;
• a message identity was normalized from a supplied channel and post ID;
• duplicates were removed according to the published key;
• the emitted metrics equal normalized supplied values;
• the attention ratio follows the published formula;
• freshness follows the supplied date and processing time;
• stable and input digests follow canonical JSON hashing;
• each attempted paid operation was serialized;
• each confirmed paid row had an exact named-event +1 delta;
• the terminal OUTPUT counters reconcile the Actor's own operations.

Evidence the Actor cannot prove

It cannot prove that:

• the buyer had the underlying rights despite the attestation;
• a Telegram export was generated by Telegram Desktop rather than another system;
• the supplied channel exists or belongs to the buyer;
• a source URL resolves or matches the record;
• views, subscribers, reactions, replies, or forwards are current or accurate;
• text is complete, truthful, non-infringing, or free of personal data;
• a priority predicts a future result;
• repeating a topic or format will reproduce prior performance;
• a downstream publication is lawful, appropriate, or approved.

Data quality boundaries

One input is one snapshot. The Actor has no durable cross-run baseline and deliberately says change.not_measured. It does not infer missing metrics as zero. A missing subscriber count makes attentionRate:null. A missing reaction count becomes an explicit confidence gap. A stale record remains deliverable because stale evidence may still be useful as a baseline, but its recommended action asks for a newer authorized export before acting.

Message text is capped at 4,000 characters. That protects storage and output bounds, but it means the Actor is not a lossless archive. Preserve the original authorized source outside Apify if exact text retention is required.

Privacy boundaries

Telegram messages may contain names, usernames, opinions, political views, health information, location, contact details, employment information, or copyrighted material. Do not submit such data merely because it appeared in a channel. Apply a documented purpose, minimization, lawful basis where required, access control, retention period, correction process, deletion process, and data-subject or channel-owner handling procedure.

For ordinary content analytics, remove names, handles, phone numbers, email addresses, private links, and sensitive free text unless they are necessary and authorized. Do not use the output to infer protected traits, evaluate individuals, target vulnerable people, make employment or credit decisions, or create a reusable people database.

Apify persists Actor input and run storage according to workspace settings. Secret-marking a field is not the same as preventing storage; this Actor accepts no credential field at all. Delete Input, Dataset, and KVS records when the authorized purpose ends.

Security boundaries

The runtime makes no network request. Recorded URLs are parsed only to retain an HTTPS Telegram URL when syntactically valid. They are never resolved, followed, fetched, rendered, or scanned. This removes SSRF and credential-forwarding surfaces from the Actor's business flow, but it does not make a recorded URL safe for a human to open.

The Actor does not accept Telegram session strings, bot tokens, phone codes, cookies, or API keys. Do not put those values in text, unknown properties, channel labels, or URLs.

Decision routing

Priority is a review order, not a business recommendation.

HIGH

A record is HIGH when it is fresh and the supplied views-to-subscribers ratio is at least 0.5. The recommended action is to review the post now and consider its demonstrated topic or format only after human editorial approval.

This rule does not say the post was successful. The ratio may reflect timing differences, forwarding, paid distribution, channel growth, a small denominator, or measurement quirks. It says only that the supplied snapshot passes a transparent review threshold.

MEDIUM

A record is MEDIUM when it is not stale and it has either a calculated ratio or a supplied view count. The recommended action is to compare it with neighboring records before reusing a topic or format.

LOW

A record is LOW when it is stale or has too little supplied context for the higher routes. The recommended action is to retain it as baseline evidence and collect a newer authorized export before acting.

Confidence

Confidence describes evidence completeness available to this Actor, not probability that a business claim is true. The basis always includes record-shape validation, stable channel/post identity, and the presence of the buyer's authorization attestation. Gaps include missing metrics, absence of a cross-snapshot baseline, and the fact that buyer-supplied records are not independently verified.

Recommended action and automation

Recommended actions are intentionally review verbs: review, compare, retain, collect. They do not say publish, delete, target, contact, or spend. safeToAutomate:false prevents a downstream integration from treating the row as permission to take a consequential action without an explicit independent approval layer.

Commercial playbooks

Weekly owner-channel review

1. Export only the latest approved review window.
2. Remove private and unnecessary fields.
3. Run no more than 100 records.
4. Confirm OUTPUT.status, delivery partition, and named-event counts.
5. Sort the Dataset by priority and freshness.
6. Review HIGH rows against the actual content and editorial goals.
7. Record the human decision in your own system.
8. Delete the run when the retention period ends.

This playbook is suitable for a team analyzing its own channel. It is not a competitor-monitoring licence.

Agency client review

Create a separate Task or controlled workflow per client. Keep the client's authorization and source instructions outside the Actor. Use one run per purpose and client. Do not merge client exports merely to save start charges. Restrict storage access to the authorized team. Deliver only the fields the client approved. Delete or archive according to the client agreement.

Editorial retrospective

Use a bounded historical sample to identify records that deserve discussion. A retrospective should compare like-for-like message windows and metric definitions. The Actor does not normalize changes in subscriber count over time and does not know when views were measured. Treat attention ratio as a supplied-snapshot descriptor, not a longitudinal KPI.

Content evidence handoff to CRM or project management

Store stableId, summary, priority, recommendedAction, confidence.gaps, and the authorized internal reference. Do not treat sourceUrl as verified. Keep the current-run OUTPUT link so the receiving team can tell whether Dataset delivery and named-event settlement were confirmed.

Controlled baseline collection

Run periodic authorized exports and retain output only if your organization has approved the retention. This Actor does not itself compare periods. A separate change processor may compare stable IDs and snapshots, but it must preserve dates, source context, and metric definitions. Do not describe two snapshots as causal evidence.

Legacy migration

If an existing integration sends channel strings, do not immediately automate a retry with message data. First decide which authorized archive will replace public preview scraping, update the Task input, test two records, verify Dataset and OUTPUT, and only then enable the schedule. The free legacy diagnostic is a migration signal, not a failed attempt to scrape.

Integration recipes

Apify API

Start an Actor run with authorized JSON using your Apify token in the API authorization mechanism, never inside the business input. A conceptual request is:

curl -X POST "https://api.apify.com/v2/acts/zinin~telegram-channel-intel/runs?token=$APIFY_TOKEN&maxTotalChargeUsd=0.02" \
  -H "Content-Type: application/json" \
  --data-binary @authorized-telegram-input.json

Do not commit the token or input export. Poll the run ID returned by Apify. Read both the default Dataset items and default KVS OUTPUT after the run reaches a terminal status.

Apify Task

Use a Task when the source schema and retention process are stable. Keep only non-sensitive defaults in the Task. Inject the current authorized message batch at invocation time. A scheduled Task should fail visibly when its upstream export is absent; do not fall back to public scraping.

JavaScript client

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const input = JSON.parse(await fs.promises.readFile('authorized-telegram-input.json', 'utf8'));
const run = await client.actor('zinin/telegram-channel-intel').call(input, {
  maxTotalChargeUsd: 0.02,
});
const dataset = await client.dataset(run.defaultDatasetId).listItems();
const output = await client.keyValueStore(run.defaultKeyValueStoreId).getRecord('OUTPUT');

if (!output?.value || output.value.runId !== run.id) throw new Error('current-run receipt missing');
if (output.value.run.unknownDeliveryCount || output.value.run.unknownSettlementCount) {
  throw new Error('manual settlement reconciliation required; do not retry automatically');
}

Python client

import json
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
with open("authorized-telegram-input.json", encoding="utf-8") as handle:
    actor_input = json.load(handle)

run = client.actor("zinin/telegram-channel-intel").call(
    run_input=actor_input,
    max_total_charge_usd=0.02,
)
rows = client.dataset(run["defaultDatasetId"]).list_items().items
output = client.key_value_store(run["defaultKeyValueStoreId"]).get_record("OUTPUT")["value"]
assert output["runId"] == run["id"]
assert output["run"]["deliveredRowCount"] == len(rows)

Webhook

Use an Apify run-finished webhook to trigger a receiver that reads terminal status and KVS OUTPUT. The webhook event alone is not proof that the paid rows settled. The receiver should reject a missing or prior-run runId, inspect unknown counts, reconcile Dataset length, and route partial or failed runs to a human queue.

MCP or agent workflow

An agent may prepare a bounded input or summarize already-delivered rows, but it must not invent the authorization confirmation. Require a human-controlled workflow to establish rights before the run. The agent should never blind-retry unknown_delivery or settlement_unknown. It should surface the exact OUTPUT state and ask for manual reconciliation.

Spreadsheet

Export the Dataset to CSV or connect through Apify. Retain stableId, priority, recommendedAction, confidence, freshness, metrics, and billing. Object fields may appear as serialized JSON depending on the connector. Store the KVS OUTPUT URL or run ID next to the imported batch so settlement evidence is not separated from the rows.

Warehouse

Use stableId as a deterministic record key scoped to this Actor contract, and retain observedAt plus requestDigest. Do not overwrite an older snapshot solely because the stable ID matches; the same message can have later supplied metrics. Model snapshots separately if historical comparison is required.

Operating guide

Before every run

• confirm source ownership or documented processing permission;
• confirm the purpose and data minimization;
• remove credentials and unnecessary personal data;
• validate that channel and post identities are present;
• use a small explicit maxTotalChargeUsd during integration;
• ensure the pricing page still shows only Actor start and result-found;
• ensure the receiving team knows that metrics are buyer-supplied and unverified.

After every run

• check Apify terminal status;
• read current-run KVS OUTPUT;
• compare runId with the platform run ID;
• compare Dataset length with confirmedDatasetWrites;
• compare paidRowCount with confirmedEventDelta and platform result counters;
• investigate any unknown, withheld, free, invalid, duplicate, partial, budget, or fatal state;
• inspect confidence gaps before using priority;
• apply retention and deletion rules.

Monitoring

Monitor these conditions:

Condition	Response
status:COMPLETE and no unknown counts	Continue to human content review.
status:PARTIAL with budget stop	Review delivered rows; raise cap only in a deliberate new run.
free legacy diagnostic	Migrate upstream to authorized message records.
invalid records	Correct source mapping; do not coerce values blindly.
unknown_delivery	Stop automation; inspect Dataset and counters manually.
settlement_unknown	Treat Dataset write as known and payment as unknown; do not retry.
pricing misconfigured	Verify exact tier event map and platform state before a new run.
missing current run ID	Treat as platform/runtime failure; no result push should occur.
KVS OUTPUT absent	Use platform run status and logs; do not infer success from Dataset alone.

Replay policy

This Actor has no cross-run idempotency journal. A new run can deliver and charge the same normalized message again. stableId helps a buyer detect that condition but does not stop the platform operation across separate runs. Use your own run orchestration, input batch IDs, and downstream uniqueness controls when repeat delivery would be harmful.

Within one run, the Actor never retries a linked paid push. Before a push, a failure is replay-safe at the result level. After any attempted push, replay safety is false unless the platform conclusively reports a free, limit-reached result; even then, create a new run only after reviewing OUTPUT and the buyer's goal.

Performance and limits

The Actor accepts at most 100 records and processes paid operations serially. This is deliberate. Serial settlement prevents two workers from passing the budget check together and overspending the buyer's cap. The calculation is local and has no network variable cost. Runtime is dominated by Apify storage and event settlement rather than content analysis.

Text is capped at 4,000 characters per message. Channel labels, IDs, and URLs are bounded. The Actor uses SHA-256 for deterministic identities and canonical object-key ordering for request and record digests.

Change management

Pin schemaVersion. Treat a new schema version as a contract migration. Keep example fixtures and mutation tests with the producer. Do not assume unknown properties will become output. Validate Dataset and OUTPUT after any Actor version change, pricing change, Task change, or upstream export change.

Incident handling

For a delivery incident:

1. preserve the run ID, Dataset ID, KVS ID, build ID, input digest, and terminal logs;
2. do not rerun automatically;
3. inspect whether the Dataset contains the last stable ID;
4. inspect platform charged-event counters;
5. compare them with OUTPUT before/after counters and last attempt;
6. classify the event as pre-push failure, unknown delivery, known Dataset/unknown settlement, confirmed free, confirmed paid, or anomaly;
7. decide manually whether a new run is appropriate;
8. avoid changing production code until root cause is identified.

FAQ

Does this Actor scrape Telegram?

No. It makes no Telegram or other network request. It processes message records supplied in Actor input.

Can I submit a public channel handle?

The legacy items field still accepts strings for backward compatibility, but the Actor will not fetch them. It writes a free migration diagnostic. Supply authorized message objects to receive post intelligence rows.

Do I need a Telegram bot token or session?

No, and the Actor does not accept those credentials. Do not put credentials in message text or other fields.

Can it analyze a Telegram Desktop JSON export?

Yes, for bounded export-style message objects after you map or provide a default channel and confirm you are authorized to process and deliver the records. The Actor is not a general parser for every Telegram export object type; unsupported records are rejected or counted as invalid.

Does authorization confirmation prove my rights?

No. It records your attestation and allows the Actor to enforce a clear product boundary. You remain responsible for the actual rights, purpose, notices, contracts, licences, and retention obligations.

Why is scrapedAt still present?

Backward compatibility. It now equals processing time and does not mean scraping occurred. New integrations should use processedAt or observedAt.

Is views divided by subscribers an engagement rate?

No. It is named attentionRate only as a supplied-snapshot review signal. It does not measure unique reach, clicks, reactions, conversions, quality, or causality.

Does HIGH priority mean I should repost the message?

No. It means the record meets a deterministic triage rule and deserves human review. safeToAutomate remains false.

Are duplicate records billed?

No intentional result event is emitted for later records with the same normalized channel/post identity in the same run.

What happens to an invalid record?

It is counted in OUTPUT. When there are invalid records alongside processable input, the Actor can write a free diagnostic row. Invalid records never become a paid result.

Why process rows serially?

Because budget check, Dataset delivery, and named-event settlement form one money-critical operation. Serial processing prevents concurrent workers from overshooting a finite charge cap.

What if the Dataset push throws?

The outcome may be ambiguous. The Actor stops, records unknown_delivery, marks replay unsafe, and never retries the row. Inspect Dataset and platform counters manually.

What if Dataset push returns but the counter read fails?

Dataset delivery is known and payment settlement is unknown. OUTPUT increments delivered rows and unknownSettlementCount, then fails without retry.

Can I safely rerun the same input?

Not automatically. Each new run has a start event and can deliver and charge the same messages again. Use stable IDs and an external idempotency policy.

Does the Actor store my input?

Apify run storage includes the Input and produced Dataset/KVS records according to workspace settings. Use appropriate access controls and delete the run when the purpose ends.

Does the Actor verify recorded Telegram URLs?

No. It retains only a syntactically valid Telegram HTTPS URL and never fetches it. Treat it as buyer-supplied context.

Can I use it for private groups?

Only if you legitimately obtained and are authorized to process the specific exported records for the stated purpose. The Actor itself does not join, access, or monitor a private group.

Can I use it for competitors?

Do not assume public visibility grants commercial processing rights. Use only records and purposes covered by your authorization, applicable terms, and law. The product is designed first for owner-authorized or contract-authorized archives.

Does it publish or message users?

No. It has no publishing or messaging path.

What proves a row was paid?

The same run's KVS OUTPUT and platform event evidence: exact before/after named result-found counter delta, paid row count, and terminal state. Dataset billing intent alone is not proof.

contract/output-record.schema.json is the structural stage only. Complete acceptance requires the bundled fail-closed semantic stage: pipe the receipt to npm run validate:output, or call validateOutputContract from lib/validate-output.js. Structural-only validation is not acceptance because JSON Schema alone does not reconstruct the work, Dataset, named-event, replay, and terminal partitions.

What should an agent do with an unknown state?

Stop. Surface the run, Dataset, KVS, and counter evidence to a human. Never issue a blind retry.

Is the result legal or compliance advice?

No. It is a technical evidence-processing output. Consult qualified advisers for legal, privacy, employment, regulatory, or contractual decisions.

Sources and rights

Product source model

The Actor uses only buyer-supplied records. It has no Telegram source client. It does not access Telegram websites, the Bot API, MTProto, Telethon, a user session, a browser, a proxy, or a third-party dataset. Therefore the Actor's source evidence is the exact authorized input and its digests, not an external retrieval claim.

The recommended source is an export or archive the buyer owns or is contractually authorized to process. Telegram Desktop export is one possible format, not an endorsement or automatic licence. Buyers should consult the current Telegram terms, content-licensing rules, privacy policy, the rights of channel and content owners, their own agreements, and applicable law before submitting records.

Official Telegram references relevant to that independent assessment include:

• Telegram Terms of Service
• Telegram Terms of Service for Content Licensing
• Telegram Privacy Policy
• Telegram FAQ

These links are documentation for the buyer's review. The Actor does not fetch them during a run, snapshot their terms, or certify compliance.

Copyright and content rights

Message text, images, files, names, and other records may be protected by copyright or other rights. This Actor processes only text and supplied metadata in the current contract; it does not fetch media. A right to access a message is not necessarily a right to republish, resell, combine, profile, or retain it. Keep the output within the scope of the source permission and approved purpose.

Privacy and organizational responsibility

The buyer determines why the data is processed, which fields are necessary, who may access them, how long they remain, and how correction or deletion requests are handled. The buyer should document the relationship among Telegram, channel owner, exporter, agency, Apify workspace, downstream systems, and recipients as required by its jurisdiction and contracts.

Do not use this tool to evade access controls or build a shadow archive of records outside the approved source context. Do not submit secret sessions, private invite links, access tokens, or sensitive personal data. Do not interpret authorizationConfirmed:true, a valid row, or evidenceAccepted:true as a legal opinion.

Release and evidence status

The two run-bound JSON examples above are explicitly local contract fixtures until the single immutable candidate build and no-retry canary are accepted. They prove the current repository's testable shape, not current public production. The release process replaces them with actual immutable build/run projections before terminal Store acceptance. The public Store page, Input page, Dataset, KVS OUTPUT, event counters, pricing, README visuals, and exact build are then checked together.

Final operating boundary

Use this Actor when you already have authorized Telegram message records and need a bounded, auditable, human-review layer. Do not use it as a way to acquire records you do not have the right to process. Evidence quality starts with source rights, minimization, and truthful input; deterministic code cannot repair an unauthorized or misleading source.