Analytics

Seven reports on how support is doing: how much comes in, how fast it is

answered, what earns money and how the AI operator copes. These are the same numbers you see in the «Аналитика» section of the app — the same code computes them.

Requires the analytics:read scope.

Why not just count the conversations yourself

Because counting by hand is slow and wrong. Conversations are paginated, so answering «how many did we close last week» by listing them runs into the page size and returns a number that is simply not true. One report call answers it exactly.

curl -H "Authorization: Bearer $TGDESK_API_KEY" \
  "https://api.tg-desk.com/v1/analytics/overview?from=2026-09-01&to=2026-09-13"

Period and filters

Every report takes the same parameters.

Filters accept a comma-separated list or a repeated parameter, whichever suits your client:

?channel=telegram,website
?channel=telegram&channel=website

The period must not exceed 366 days. A longer one is refused with validation_failed rather than quietly clamped: a clamped answer would answer a different question, and you would never know.

To avoid guessing filter values, ask for them:

curl -H "Authorization: Bearer $TGDESK_API_KEY" \
  https://api.tg-desk.com/v1/analytics/filters

You get back only the channels, teams and people that actually appear in your data.

The reports

A report is a whole answer, not a page of a list, so there is no cursor here.

What to know about the numbers

`null` is not zero. Where a value cannot honestly be computed, you get null, and that is a different statement. The resolved share on a day with no new dialogs is null, not 0 %. A week's average score with nothing scored is null, and the line should break rather than drop to zero.

The clearest case is autonomous_share in the AI-operator report. While the agent runs in draft mode a human sends every reply, so the share closed with no human is not zero — it is not measurable. You get null, with autonomous_share_blocked_reason set to draft_mode_only beside it, so you can explain the gap instead of drawing a 0 %.

Shares are numbers from 0 to 1, not percentages. 0.6 means 60 %.

Revenue is never converted between currencies. Each currency is its own row in by_currency. Adding them up is your decision and your exchange rate.

Revenue has a recognition axis. The recognition parameter chooses which date the money counts on: won — the date the deal was won (the default), dialog — the date of the conversation, created — the date the deal was created.

Permissions and visibility

A key reports on the whole project. So only a person who themselves sees every conversation can create a key with this scope: if their own visibility is set to «own» or «own team», minting such a key is refused. Otherwise the API would show more than the app does.

analytics:read includes revenue. Someone without rights to the money reports cannot create such a key at all.