Analytics

What TelegramOS analytics measure: sent and received message events per account, the per-user privacy switch, AI insights, exports and retention.

Analytics are built from one event stream: every message your accounts send, and every conversational message they receive, is written to ClickHouse as an account_events row. The Analytics page, the dashboard cards and the per-account counters all read that table. Analytics requires a plan with the analytics capability (all paid plans and the trial).

What is tracked

Replies from Telegram's SpamBot health probe are excluded from every count. Nothing is recorded about response times, conversation length, bot command usage or reactions; the reactions_given field in the API is always 0.

Dashboard

Pick a window of 7, 14, 30 or 90 days. Every block compares the window with the one immediately before it.

• Headline cards: messages sent, messages received, active accounts (accounts with at least one event) and response ratio (received divided by sent), each with a percentage change.
• Message volume: daily sent and received.
• Where messages flow: sent and received by counterparty type.
• Outbound composition: regular, reply and forward sends.
• Inbound media: incoming messages by media type.
• Activity by hour: 24 UTC buckets.
• Account spam and health timeline: per account or fleet-wide, up to 180 days. Messages and flood waits come from ClickHouse; the health score is the hourly snapshot in account_health_log (pruned after 90 days) and the spam status is the daily SpamBot verdict. Health and spam lines start when logging began for that account.
• Top accounts: the ten busiest accounts in the window.
• AI insights: a button that requests a written summary (see below).

Export CSV writes the report on screen (totals, deltas, composition, peer distribution, media, hourly activity, top accounts) to a file in the browser. There is no scheduled export and no raw event export.

The Accounts page shows today's sent and received counts and groups joined per account, read from the same table and cached for 60 seconds.

Privacy switch

Settings > Privacy > Message analytics is a per-user flag (analytics_enabled, on by default).

Turning the switch off stops reading, not writing: events keep being ingested, nothing is anonymised or deleted, and turning it back on shows the full history. If the flag cannot be read because of a database error, analytics behave as if it were off.

For teams, the owner's switch governs the owner's data: a member with analytics:read sees a team's analytics only while that team's owner has the switch on.

AI insights

AI features are controlled by a deployment-wide AI_ENABLED flag.

• Off: Generate insights returns a statistical summary computed from the same week-over-week signals (trend, per-account outliers, a volume anomaly check). No model is called.
• On: the signals are sent to the configured model and the reply is shown. If the call fails, the statistical summary is returned instead.

When the model is on, AI actions count against a monthly per-plan allowance (Free 10, Starter 500, Growth 5,000, Agency unlimited; deployment-configurable). The other AI endpoints (conversation summary, reply suggestions, sentiment, send-risk, template variations, daily digest) are on-demand and count against the same allowance. No incoming message is analysed by a model unless you trigger it.

Retention

API limits

• A requested date range may span at most 366 days.
• Hourly granularity on /analytics/daily is limited to a 7-day window.
• Timelines accept 1 to 180 days; anomalies 1 to 30 days; velocity 1 to 168 hours.