Channel statistics

Telegram offers detailed channel statistics for channels and supergroups.

Channel statistics

Schema:

statsDateRangeDays#b637edaf min_date:int max_date:int = StatsDateRangeDays;

statsAbsValueAndPrev#cb43acde current:double previous:double = StatsAbsValueAndPrev;

statsPercentValue#cbce2fe0 part:double total:double = StatsPercentValue;

statsGraphAsync#4a27eb2d token:string = StatsGraph;
statsGraphError#bedc9822 error:string = StatsGraph;
statsGraph#8ea464b6 flags:# json:DataJSON zoom_token:flags.0?string = StatsGraph;

messageInteractionCounters#ad4fc9bd msg_id:int views:int forwards:int = MessageInteractionCounters;

stats.broadcastStats#bdf78394 period:StatsDateRangeDays followers:StatsAbsValueAndPrev views_per_post:StatsAbsValueAndPrev shares_per_post:StatsAbsValueAndPrev enabled_notifications:StatsPercentValue growth_graph:StatsGraph followers_graph:StatsGraph mute_graph:StatsGraph top_hours_graph:StatsGraph interactions_graph:StatsGraph iv_interactions_graph:StatsGraph views_by_source_graph:StatsGraph new_followers_by_source_graph:StatsGraph languages_graph:StatsGraph recent_message_interactions:Vector<MessageInteractionCounters> = stats.BroadcastStats;

---functions---

stats.getBroadcastStats#ab42441a flags:# dark:flags.0?true channel:InputChannel = stats.BroadcastStats;
stats.loadAsyncGraph#621d5fa0 flags:# token:string x:flags.0?long = StatsGraph;

Administrators of channels of a certain size (the exact limit is a server-side config, returned in the can_view_stats flag of channelFull) can call stats.getBroadcastStats to get detailed channel statistics.
The returned stats.broadcastStats contains multiple statistics:

• Period-related statistics: a pair of values, one at the beginning and one at the end of the period in consideration (period).
  The period typically depends on channel activity.
  • Absolute follower count (followers)
  • total_viewcount/postcount, for posts posted during the period in consideration (views_per_post).
    Note that in this case, current refers to the period in consideration (min_date till max_date), and prev refers to the previous period ((min_date - (max_date - min_date)) till min_date).
  • total_sharecount/postcount, for posts posted during the period in consideration (shares_per_post).
    Note that in this case, current refers to the period in consideration (min_date till max_date), and prev refers to the previous period ((min_date - (max_date - min_date)) till min_date).
• Percentage statistics
  • Percentage of subscribers with enabled notifications (enabled_notifications)
• Graphs: graphs are described below ».

Supergroup statistics

Schema:

statsGroupTopPoster#9d04af9b user_id:long messages:int avg_chars:int = StatsGroupTopPoster;
statsGroupTopInviter#535f779d user_id:long invitations:int = StatsGroupTopInviter;
statsGroupTopAdmin#d7584c87 user_id:long deleted:int kicked:int banned:int = StatsGroupTopAdmin;

stats.megagroupStats#ef7ff916 period:StatsDateRangeDays members:StatsAbsValueAndPrev messages:StatsAbsValueAndPrev viewers:StatsAbsValueAndPrev posters:StatsAbsValueAndPrev growth_graph:StatsGraph members_graph:StatsGraph new_members_by_source_graph:StatsGraph languages_graph:StatsGraph messages_graph:StatsGraph actions_graph:StatsGraph top_hours_graph:StatsGraph weekdays_graph:StatsGraph top_posters:Vector<StatsGroupTopPoster> top_admins:Vector<StatsGroupTopAdmin> top_inviters:Vector<StatsGroupTopInviter> users:Vector<User> = stats.MegagroupStats;

---functions---

stats.getMegagroupStats#dcdf8607 flags:# dark:flags.0?true channel:InputChannel = stats.MegagroupStats;

Administrators of supergroups of a certain size (the exact limit is a server-side config, returned in the can_view_stats flag of channelFull) can call stats.getMegagroupStats to get detailed supergroup statistics.
The returned stats.broadcastStats contains multiple statistics, see the constructor page for more info ».

Message statistics

stats.messageStats#8999f295 views_graph:StatsGraph = stats.MessageStats;

---functions---

stats.getMessageStats#b6e0a3f5 flags:# dark:flags.0?true channel:InputChannel msg_id:int = stats.MessageStats;

Administrators of channels of a certain size (the exact limit is a server-side config, returned in the can_view_stats flag of channelFull) can call stats.getMessageStats to get statistics of a specific message.
The returned stats.messageStats contains the view graph of the message.

Graph visualization

There are four available visualizations for graph types:

• Line graph
• Step graph
• Bar graph
• Area graph

Graph modifiers (see various graphs for examples):

• y_scaled - Indicates that each of the two (!) lines in a step graph must be visualized on its own scale, with two different tick axes on the left and right parts of the graph
• percentage - Indicates whether value percentages should be shown in labels
• stacked - Depending on the graph type, indicates stacking of multiple columns in the same graph

Graph syntax

statsGraphAsync#4a27eb2d token:string = StatsGraph;
statsGraphError#bedc9822 error:string = StatsGraph;
statsGraph#8ea464b6 flags:# json:DataJSON zoom_token:flags.0?string = StatsGraph;

dataJSON#7d748d04 data:string = DataJSON;

---functions---

stats.loadAsyncGraph#621d5fa0 flags:# token:string x:flags.0?long = StatsGraph;

Certain graphs are not directly sent in the stats.broadcastStats constructor to reduce server load: instead, those graphs will be sent as a statsGraphAsync constructor, and should be fetched separately using stats.loadAsyncGraph.

After obtaining the full statsGraph constructor, clients should parse the JSON graph object in the json field.

Object structure:

The following chart restrictions apply:

• Up to 50 columns on one graph must be supported.
• Chart types are always the same for every column in the graph.
• The bar chart type and stacked option are always used together.
• percentage is always used with the area graph.

Chart zooming

statsGraphError#bedc9822 error:string = StatsGraph;
statsGraph#8ea464b6 flags:# json:DataJSON zoom_token:flags.0?string = StatsGraph;

dataJSON#7d748d04 data:string = DataJSON;

---functions---

stats.loadAsyncGraph#621d5fa0 flags:# token:string x:flags.0?long = StatsGraph;

Graphs that support zooming will contain a zoom_token in the statsGraph constructor.
Said token should be then used as token in a new stats.loadAsyncGraph call triggered when the user clicks on the label, related to a certain x axis in the graph (see graph examples).
The x coordinate of the label should be provided to the x parameter; the method will then return (if available) a more detailed subgraph.
If not enough data is available, a localized statsGraphError will be returned.

Typical zoom visualization rules:

• Any percentage graph (even if a zoom_token is not available) => piechart
• line graph => line graph
• step graph => step graph
• bar graph => bar graph
• area graph => area graph

Chart colors

Chart colors can be provided as a color key, followed by the primary color value in hex format:

red#e05356

The color key can be one of red, lightblue, lightgreen, golden, green, orange, blue, indigo.
Apps can choose to use a color value specified by the currently loaded theme: for example, the android app uses statisticChartLine_* themekeys for each of the color keys, check out the assets directory for a bunch of default themes with various colors for channel statistics.

However, the server may also choose to return just a plain color value in hex format:

#e05356

In this case, the dark flag of the stats.getBroadcastStats method can be used to choose the palette of returned colors.

Graph examples

Line graph

Simple single line graph

Step graph

Step graph, always "stacked" (to indicate multiple lines)

Bar graph

Bar graph with multiple lines, always "stacked" (to indicate actual stacked bars, biggest bars first)

Area graph

Mixed bar/line graph, always "stacked" (to indicate actual stacked bars, biggest bars first)

Piechart

Piechart, typically obtained only when zooming into percentage graphs