Channel statistics

Telegram offers detailed channel statistics for channels with more than 500 subscribers.

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 with more than 500 subscribers 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 ยป.

Graph visualization

There are four available visualizations for graph types:

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:

Key Graph title
columns Array of all data column arrays in the chart. Each column array has its label at position 0, followed by values.
types Graphs types for each of the column arrays (object, "label": "type"):
- line - line graph
- area - area graph
- step - step graph
- bar - bar graph
- x - x axis values for each of the charts at the corresponding positions, UNIX timestamps in milliseconds.
colors Color for each type (object, "label": "colorKey#AAAAAA"; see chart colors).
names Localized name for each variable (object, "label": "Name")
subchart Object indicating the default zoom range for the graph, this is object's structure:
- show - Whether to use the specified zoom range (boolean)
- defaultZoom - An array with two x values, indicating the two ends of the default zoom range
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 (boolean, see various graphs for examples)
percentage Indicates whether value percentages should be shown in labels (boolean, see various graphs for examples)
stacked Depending on the graph type, indicates stacking of multiple columns in the same graph (boolean, see various graphs for examples)

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:

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