# Telegram Ads: как работает коннектор

В этой статье вы узнаете, как коннектор Telegram Ads выгружает данные в хранилище ROMI center: с какой периодичностью, как устроен обход кабинета и откуда берутся UTM-метки. Полный список полей — в статье [Telegram Ads: описание выгружаемых полей](https://help-ru.romi.center/telegram-ads-opisanie-vygruzhaemyh-polej).

## Главное отличие: у Telegram Ads нет API

Telegram не отдаёт статистику рекламы через API, поэтому коннектор работает как робот в личном кабинете `ads.telegram.org`: заходит под сохранённой сессией и забирает данные так же, как это делал бы человек — список объявлений аккаунта, CSV-выгрузки показов/кликов/подписок и потраченного бюджета по каждому объявлению, карточку объявления с настройками.

Из этого вытекают все остальные особенности: выгрузка медленная и зависит от вёрстки кабинета.

> **Важно**
> Доступ общий, а не клиентский. Сессия берётся из служебного справочника активных доступов Telegram, а конкретный рекламный аккаунт выбирается подстановкой его логина. Если активный доступ протух, перестают выгружаться все подключения Telegram Ads сразу, а не одно.

## Периодичность

Выгрузка идёт раз в сутки. Окно урезано до двух дней — «вчера» и «сегодня минус 7», без промежуточных дней (у остальных рекламных коннекторов перезагружаются все 7 дней подряд). Причина — длительность прогона: полный обход кабинета за каждый из семи дней занял бы недопустимо много времени.

## Как собираются данные: перебор объявлений

1.  Из кабинета берётся список объявлений — столько, сколько кабинет отдаёт на странице.
2.  По каждому объявлению забираются две CSV-выгрузки (статистика и бюджет) и карточка объявления.
3.  Если в списке оказалось 100 объявлений или больше, включается перебор по идентификаторам вниз: кабинет показывает не всё, поэтому коннектор идёт от минимального известного идентификатора к первому, проверяя каждый.
4.  Идентификаторы, за которыми уже нет объявления, запоминаются в подключении и в следующие разы не проверяются.

> **Примечание**
> Чем дольше живёт рекламный аккаунт, тем дольше идёт выгрузка — список идентификаторов только растёт. Именно поэтому окно и урезано до двух дней.

Гранулярность данных: строка = объявление × день.

## Как сохраняет данные

*   **Куда:** хранилище ROMI center на движке ClickHouse.
*   **Имя таблицы:** `telegram_ads_<транслитерированное название аккаунта>_<id подключения>`.
*   **Структура таблицы:** движок `MergeTree`, сортировка по `stats_day`, разбиение на партиции по дню статистики.
*   **Порядок колонок:** общие поля (`stats_day`, `utm_*`, `cost`) → колонки конвертации валют → выбранные поля → служебные `rc_import_id`, `rc_created_at`.
*   **Структура догоняется, а не пересоздаётся.** Недостающие колонки добавляются при очередной выгрузке, существующие не удаляются.
*   **Типы приводятся при записи:** булевы — к «да/нет», дробные — к числу с плавающей точкой, целые — к целому.

## Перезапись данных

Каждое задание перезаписывает свой день целиком: если строк нет, день пропускается и прежние данные сохраняются; если строки есть, весь день удаляется и записывается заново. Штатно так перезаписываются только два дня — «вчера» и «сегодня минус 7». Дни между ними остаются такими, какими были выгружены ранее.

Ручная перезагрузка за произвольный период доступна в кабинете и ставит задания на каждый день выбранного интервала — здесь ограничения в два дня нет. Учитывая скорость обхода кабинета, длинный интервал стоит запускать с запасом по времени. При включённой опции «удалить данные» таблица сносится целиком и создаётся заново первой же выгрузкой.

## Дополнительные настройки

| Настройка | Что делает |
| --- | --- |
| Рекламный аккаунт | Аккаунт Telegram Ads, из которого забирается статистика. Его название входит в имя таблицы. |
| Выбор полей | Задаёт набор колонок таблицы. Восемь общих полей выгружаются всегда, остальные 14 включаются по выбору. |
| НДС | При включённой настройке ROMI center добавляет НДС к расходу по указанной ставке. |
| Конвертация валют | На каждую выбранную валюту добавляется колонка `cost_converted_<валюта>` — расход, пересчитанный по курсу на дату строки. Исходная валюта у Telegram Ads всегда евро. |
| UTM-метки для всех кампаний | Подменяет `utm_source`, `utm_medium`, `utm_campaign` заданными значениями во всех строках. |
| UTM-метки для выбранных объявлений | То же, но для конкретных объявлений: у Telegram Ads роль «кампании» играет объявление, по его идентификатору и идёт сопоставление. |
| Пауза коннектора | Останавливает создание новых заданий. |

> **Примечание**
> Настройка «Фильтр объявлений» осталась от старого интерфейса: новый визард её не задаёт и при каждом сохранении обнуляет.

> **Важно**
> Доступ перед выгрузкой не проверяется. У остальных площадок серии перед каждым прогоном проверяется живой токен. У Telegram Ads такой проверки нет: прогон стартует всегда, и если общая сессия протухла или аккаунт пропал из кабинета, робот просто не найдёт данных — задание завершится «успешно», но строк за день не будет, а прежние данные останутся нетронутыми (пустой ответ день не очищает). Отслеживать такие случаи нужно по отсутствию свежих строк, а не по статусу подключения.

## Откуда берутся UTM-метки

Единственный источник — ссылка продвижения объявления: из неё берутся все параметры, чьё имя содержит `utm`. Значения по умолчанию, если в ссылке меток нет:

| Метка | Значение по умолчанию |
| --- | --- |
| `utm_source` | `rc-telegram` |
| `utm_medium` | `rc-cpm` |
| `utm_campaign` | `rc-(not set)` |
| `utm_term` | `(not set)` |
| `utm_content` | `(not set)` |
| `utm_id` | идентификатор объявления |

Дальше применяется пользовательская подмена из настроек подключения — она правит только `utm_source`, `utm_medium` и `utm_campaign`; `utm_id`, `utm_term` и `utm_content` остаются такими, какими пришли из ссылки. Макросов, как у других площадок, у Telegram Ads нет — подставлять в ссылку нечего.

> **Примечание**
> Предупреждения «данные пришли без UTM-меток» у Telegram Ads не бывает. Судить о качестве меток можно только по самим значениям в таблице: если в колонках стоят `rc-telegram`, `rc-cpm` и `rc-(not set)`, значит в ссылке объявления меток не было.

## Технические поля

| Поле | Тип | Что означает |
| --- | --- | --- |
| `rc_import_id` | Целое число | Идентификатор прогона выгрузки, которым записана строка. |
| `rc_created_at` | Дата и время | Момент записи строки в хранилище (не время события). При перезаписи дня обновляется у всех строк дня. |

В таблицах Telegram Ads нет `rc_updated_at` и `rc_datasource`.