Reports
The Reports section is a library of ready-made breakdowns of your bot. Unlike the dashboard, where widgets are assembled by hand, every report here is already configured: choose a report, a bot and a period, and you get the answer.
How reports differ from widgets
| Reports | Dashboard widgets | |
|---|---|---|
| Setup | Ready-made, nothing to change | You build them yourself |
| Where they live | A separate section, each at its own address | On your dashboard |
| Can be shared | Yes — the link opens the report and the chosen segment together with its bot. The period is not carried in the link | No, they are stored locally in the browser |
| Explanation | Every report has an "About this report" block | No |
Reports do not replace the dashboard, they complement it: a report answers a typical question, the dashboard answers your own.
Segments in a report
Next to the bot and period there is a "Segment" field. Choose a saved segment and the report shows data for that segment only, for example "retention of paying customers".
- A segment in a report is live: if the segment changes, the report shows the new membership the next time it is opened.
- The segment goes into the link, so a report on a segment can be sent to a colleague.
- Retention accepts only segments with the "People" badge, made of conditions about the person.
- Profile-property reports, "New users", audience inflow and outflow, channel subscribers, the heatmap, churn and the funnel always count all of the bot's data: their "Segment" field is disabled.
If a segment has an event condition, in a report it narrows the events themselves, not only the people. The "Events by name" report with "pressed button X" shows only those presses. The report warns about this above the chart.
Categories
Growth
- Active users — unique people over time.
- Unique users: 1 / 7 / 30 days — the DAU / WAU / MAU triple: active over a day, a week and a month. These are three separate numbers, not a trend. The windows are rolling and end at the end of the selected period, whereas the cards on the Vitals page count the last complete UTC calendar day, week and month, so the figures on the two pages differ on purpose.
- New users — people whose first-ever event fell in the period, by interval. This is the same metric as the "New users" cards on the Vitals page: a person appears in the chart exactly once, in the interval where they first appeared.
- /start commands — people who sent
/start. It measures intent to connect, not arrival: someone who blocked the bot and started it again is counted again. This report used to be called "New users", which was wrong. - Audience inflow and outflow — who starts and who blocks the bot, as two lines on one chart.
- Channel subscribers — joins and leaves in a channel where the bot is an administrator.
Engagement
Total events, events by name and by type, traffic by connection, the activity heatmap, private chats and groups, button presses, reactions, commands, message types, attachment types, geography.
Acquisition
- Traffic sources, Campaigns and Referral codes — the
source,campaignandrefkeys of deep links such ast.me/yourbot?start=source-tgads_campaign-june. This is the closest analogue of UTM tags for a Telegram bot. The link format is described on the Users page. - Deep-link arrivals — the whole deep-link parameter, for links that carry opaque codes.
- Languages and Telegram Premium — audience demographics.
Conversion, Retention, Monetization
The onboarding funnel, cohort retention, 30-day churn and revenue by currency.
Limitations worth knowing in advance
Not all data is visible with every connection
Telegram gives different connection types different data. Metriox cannot work around that, but it marks such reports honestly with a badge.
| Badge | What it means |
|---|---|
| Bot API SDK only | Revenue |
| MTProto only | Attachment types (detail) |
| SDK / Mini App only | Geography |
If a bot has one connection, reports from the "other" group will be empty; that is not a setup error.
Two reports used to answer the same question: "Message types" (Bot API SDK only) and "Attachment types" (MTProto only). Each was empty for half of all bots, although both connections had the data, just in a different form: the Bot API names the kind of message, MTProto names the attachment.
Now there is one report, "Content types", without a badge: when an event is written, both forms are mapped
to a common vocabulary, so a photo is photo however the bot is connected. "Message types" is gone, and
"Attachment types" remains as the detail view, where the differences the common vocabulary merges are visible
(a custom emoji instead of a sticker, live location instead of a static one).
The report shows data from the moment of this update: messages written earlier kept only the original field of their particular connection.
"Commands" used to be listed here too, and that was our shortcoming, not a Telegram limitation. A command
(/start, /help@MyBot ref123) is just structure inside the message text, and the MTProto worker always saw
that text but did not parse it. Now the command, the bot mention and the parameters are extracted by a shared
parser on the write side, the same way for both connections.
The "Commands" report shows data from the moment of this update. Messages written earlier remain without a parsed command; that is a matter of recomputing history, not of data availability.
Attribution: first and last touch
Someone can arrive through one link and come back through another. The Traffic sources, Campaigns and Referral codes reports have an Attribution control, and it decides which link a person is credited to:
| Mode | Who the person is credited to |
|---|---|
| First touch (default) | the first link they arrived through |
| Last touch | the most recent link up to the end of the period |
| Link opens in period | every link they opened during the period; the rows can add up to more than the audience |
In the first two modes each person lands in exactly one row, so the rows add up to the total. The tag is read from that same link: if a person's first link carried no campaign, first touch leaves them out of Campaigns, and shares are of people with the tag rather than the whole audience. Links opened after the end of the period are not counted.
The period selects people active during the selected dates, and their link is looked up across the whole
retained history. If your plan keeps events long enough, someone who arrived in March through the spring
campaign and wrote yesterday is credited to spring in yesterday's report.
Events are kept for as many days as the plan provides. If a person's real first link is older than that, the earliest link still kept counts as their first touch, which is a later link. If no link is kept at all, the person is not in the table. So first touch is reliable only within the retention period, and the numbers change when it changes.
The chosen mode goes into the report link. The bot and the period do not: a colleague opens the report on their own last bot and the last 7 days.
Deep-link arrivals counts the latest deep link
The Deep-link arrivals report reads the user record, which holds the latest parameter as a whole, not split into keys. If someone restarted the bot through a different link, they move to a different row. This report has no attribution control.
The period in it selects users active during the selected dates and reads their record as it is now. It is not the moment of acquisition: someone acquired in March who wrote yesterday appears in yesterday's report.
The period used to filter the moment the user record was last updated, not activity. The record is not written on every visit, so a user with a long-written record did not appear in the report at all, and the advice "widen the period if a campaign looks smaller than expected" is no longer needed. Numbers for old periods went up after the update; the data did not change, the selection did.
Shares are computed by the server, not the browser
In ranking reports the "Share" column appears only when the server has sent a total. That is deliberate: the sum of the rows on screen does not equal the overall count — unique users do not add up (one person appears in several rows), the list is cut from the top, and rows without a value may be excluded. So a share is never computed from what is visible on screen.
Currencies are never added together: Metriox has no exchange rates, so a bot with several currencies gets several correct rows instead of one meaningless total. Amounts are in Telegram's smallest units (cents, kopecks or whole Stars). Only payments recorded through the Bot API SDK are counted.
What reports do not have
Sessions (count, duration, bounces), devices, the Telegram version, custom SQL. Metriox either does not collect this data or Telegram does not provide it, so such reports are not shown empty, they simply do not exist.