Telegram Ads API & интеграции: Автоматизация рабочего процесса
Telegram не публикует API для рекламодателей: на его сайте для разработчиков перечислены Bot API, клиентский API, TDLib, Gateway API и Payments API, и ни один из них не создаёт рекламные кампании и не отдаёт по ним отчёты. ADSLY подключается к вашим рекламным кабинетам через авторизованную сессию и даёт поверх неё три точки интеграции — REST API, который читает статистику, а с вашего разрешения и управляет кампаниями; подписанные вебхуки; и эндпоинт, который принимает конверсии из вашего трекера.
Как устроен «API» Telegram Ads
Рекламная платформа Telegram живёт на ads.telegram.org и управляется через веб-интерфейс. В октябре 2026 мы проверили документацию Telegram для разработчиков: на core.telegram.org представлены Bot API (с Payments API для ботов), TDLib, Gateway API и Telegram API для клиентских приложений. Про рекламу там две статьи: Sponsored Messages объясняет клиентским приложениям, как показывать объявления, а вторая посвящена рекламному доходу владельцев каналов и ботов; ни одна не предназначена для рекламодателя, который управляет кампаниями. В стартовом руководстве самой платформы API тоже не упоминается.
Поэтому ADSLY работает через сессию того Telegram-аккаунта, которому принадлежит рекламный кабинет. Подключить кабинет можно тремя способами: ввести номер телефона и подтвердить запрос в Telegram, воспользоваться нашим браузерным расширением, пока вы залогинены на ads.telegram.org, или вставить токен сессии вручную. Запрос подключает только рекламный кабинет, а не ваш личный Telegram. Кабинеты из Adstat подключаются по вашему логину Adstat. После подключения Euro-, TON- и Stars-кабинеты обслуживаются одинаково.
Что делает ADSLY, когда кабинет подключён
Всё, что в веб-интерфейсе прокликивается руками, в панели становится действием:
Создание кампаний — одна кампания с полной настройкой или массовая сборка: несколько текстов × несколько ссылок × список каналов, при желании с разбивкой на отдельную кампанию под каждую страну, тему или устройство.
Изменение CPM и бюджета — задать, поднять или снизить ставку на всех выбранных кампаниях, на сумму или на процент; добавить бюджет, уменьшить его или вывести остаток.
Пауза, запуск и удаление — для выборки, группы или всех кампаний, которые подходят под текущий фильтр.
Синхронизация статистики — показы, клики, действия, расход, CTR и CPM сохраняются раз в час по каждой кампании.
Правка текста, названия и медиа — массово, без пересоздания кампаний.
Контроль балансов — на главной перечислены все кабинеты с балансом и числом активных, проверяемых, отклонённых и остановленных кампаний; данные обновляются при каждой синхронизации.
Экспорт данных и отчётность
Панель хранит больше истории, чем видно на одной вкладке статистики, и позволяет её забрать:
Экспорт в Excel, CSV и PDF — файл с выбранными колонками или PDF-отчёт по всему кабинету, одной группе или выбранным кампаниям. Доступно на тарифах Pro и Agency.
Почасовые данные — один снапшот на кампанию в час, хранятся 30 дней; более длинные периоды считаются по дневным итогам. Общего замера по часам суток у нас нет, поэтому свои часы ищите по почасовому графику собственных кампаний.
Аналитика по всем кабинетам — страница «Аналитика» складывает показы, клики и действия по всем кабинетам, к которым у вас есть доступ. Расход остаётся разбитым по валютам: евро, TON и Stars никогда не суммируются.
История изменений — каждое изменение статуса, ставки и бюджета кампании записывается вместе с тем, кто или что его сделало, включая правила и Auto CPM.
Хуки автоматизации
Правила и автоматические действия отрабатывают после каждой почасовой синхронизации — без человека у экрана:
Правила IF/THEN — условия по показам, кликам, действиям, CTR, CVR, расходу, CPC, CPA, CPM и бюджету; каждое измеряется за всё время или за последние 1–168 часов. Действия: пауза, запуск, задать CPM, поднять или снизить CPM на сумму или на процент, добавить или уменьшить бюджет либо только уведомить. Пример: ЕСЛИ CPM за последние 6 часов выше €2,50, ТО снизить ставку на 15%. Правило вешается на одну кампанию, группу, выборку или весь кабинет.
Правила по вашим конверсиям — когда трекер начинает слать постбеки, тот же движок умеет реагировать на лиды, конверсии, покупки, выручку, ROAS, цену лида и цену продажи. Кабинет, который постбеков не шлёт, такое правило не остановит: отсутствие данных считается «неизвестно», а не «ноль».
Черновики правил на несколько кабинетов — сохранённый черновик живёт на вашем логине ADSLY, а кнопка «Применить к кабинетам» копирует его во все отмеченные кабинеты.
Auto CPM — раз в час панель проверяет, действительно ли объявление показывается в каналах и ботах, на которые оно нацелено. Показывается в большинстве — ставка снижается на 10%. Не показывается в большинстве — растёт на 10%. Нужны две проверки подряд с одинаковым выводом; между правками проходит не меньше трёх часов, и на кампанию приходится не больше шести правок в сутки.
Пересоздание и AI-пересоздание — отклонённое объявление отправляется на модерацию заново автоматически; в режиме AI-пересоздания текст на каждой попытке переформулируется. Процент «спасённых» объявлений мы не публикуем.
Сценарии интеграции для агентств
Четыре схемы, которые собираются из этих деталей:
Отчёты клиентам — выгружайте PDF или Excel по кабинету клиента или по группе либо забирайте /v1/stats в тот инструмент отчётности, которым уже пользуетесь.
Оповещения — правило с действием «уведомить» попадает в часовой дайджест, который приходит в Telegram, на почту или в приложение. Для ваших собственных систем есть вебхук status_change: он срабатывает, когда кампания переходит в Declined, Active или любой другой статус.
Собственные дашборды — /v1/stats/total отдаёт итоги и точки графика по каждому кабинету; обычная синхронизация — три-четыре запроса, что далеко от лимита в 60 запросов в минуту на ключ.
Замкнуть цикл с трекером — отправляйте лиды и продажи на эндпоинт постбеков, и в таблице кампаний рядом с колонками Telegram появятся цена лида и цена продажи. В панели есть готовые шаблоны постбеков для Keitaro, RedTrack, Binom и Voluum.
REST API и вебхуки ADSLY
API работает на тарифах Pro и Agency. Откройте API в меню, нажмите «+ Новый ключ» и выберите, к каким кабинетам у ключа будет доступ — к одному, нескольким или ко всем, — и сможет ли он ещё и управлять кампаниями. Одновременно активными могут быть до пяти ключей.
Base URL: https://app.adsly.pro/api/v1 · Авторизация: заголовок X-API-Key · Лимит: 60 запросов в минуту на ключ
Читать может любой ключ:
-
GET /v1/account/info— кабинеты, которые видит этот ключ -
GET /v1/campaigns— кампании с метриками; фильтры по статусу, названию, юзернейму бота или канала, домену лендинга и типу объявления; курсорная пагинация -
GET /v1/stats— статистика по каждой кампании за период, сгруппированная по кабинетам -
GET /v1/stats/total— итоги и точки графика по каждому кабинету -
GET /v1/stats/analytics— аналитика за период с топом кампаний -
GET /v1/campaigns/:adId/history— одна кампания за период -
GET /v1/conversions— конверсии, полученные постбеком, по кампаниям
Управление кампаниями. Пока вы не включили для ключа этот переключатель, ключ только читает. С ним он ещё и создаёт кампании (до 100 за вызов), меняет текст, ссылку, CPM и дневной лимит, ставит на паузу и запускает снова, пополняет бюджет и снимает остаток, копирует, выполняет массовые действия — до 1 000 кампаний за раз, — удаляет кампании и загружает медиа. Вывести деньги из кабинета не может ни один ключ: бюджет только переходит между балансом кабинета и его кампаниями. Каждое изменение через API видно в истории кампании в панели, а вызовы создания, бюджета, копирования и массовых действий принимают Idempotency-Key — повтор после таймаута не выполнится дважды.
Полная документация — на adsly.pro/docs/api (на английском), с Markdown-версией каждой страницы и индексом llms.txt для AI-ассистентов.
На первой интеграции спотыкаются о две вещи. Денежные поля (spent, budget, cpm, cpc, cpa, ctr) приходят строками, чтобы не терять точность, — парсите их перед арифметикой. А ad_id уникален только внутри одного кабинета: Telegram переиспользует идентификаторы, поэтому храните его всегда в паре с account_id.
Вебхуки. Укажите на ключе Postback URL — и ADSLY будет слать на него подписанный JSON: status_change, когда при синхронизации меняется статус кампании, и hourly_digest через пять минут после начала каждого часа — показы, клики, расход и действия по каждой кампании за только что закрытый час. В каждом запросе есть подпись HMAC-SHA256 в заголовке X-Adsly-Signature, метка времени и уникальный идентификатор доставки. Эндпоинт должен быть публичным и работать по HTTPS; неудачная доставка повторяется один раз.
Приём конверсий. Включите на ключе «Принимать постбеки», а дальше либо шлите POST /v1/postback со своего бэкенда с ключом в заголовке, либо отдайте трекеру write-only URL из кнопки «Сгенерировать URL для трекера». События — lead, conversion и purchase, с необязательными суммой и валютой; в один запрос помещается до 1000 событий, а ключ принимает 20 событий в секунду. Событие привязывается к кампании по значению из ссылки объявления: параметр ?start= у рекламы ботов, параметр вашего трекера у рекламы сайтов.
Безопасность и доступ
На этих кабинетах лежат реальные бюджеты, поэтому каждая точка входа намеренно узкая:
Сессия, а не пароль — кабинет Telegram Ads подключается подтверждением запроса в Telegram, через браузерное расширение или токеном сессии. Подключение распространяется на рекламный кабинет, а не на ваш личный Telegram.
По умолчанию только чтение, ключи хранятся хешами — ключ лишь читает, пока владелец не включит «Управление кампаниями», и даже с ним не может вывести деньги из кабинета. Ключи хранятся в виде хешей SHA-256, поэтому потерянный ключ нельзя восстановить — только отозвать и выпустить новый.
Подписанные вебхуки — проверяйте HMAC-подпись и отклоняйте запросы с меткой времени старше пяти минут. ADSLY не отправляет вебхуки на адреса без HTTPS, на loopback и на приватные адреса.
Доступ команды по кабинетам — на тарифе Agency каждому участнику выдаётся «Просмотр», «Менеджер» или отсутствие доступа к каждому кабинету. Участники сами создают API-ключи, и ключ достаёт только до кабинетов, открытых этому участнику: где у него «Просмотр» — только чтение, где «Менеджер» — можно вносить изменения.
Автоматизируйте работу с Telegram Ads. ADSLY управляет 500,000+ кампаниями — а Euro-кабинет открывается под любую страну. Все три типа кабинетов (TON, Euro, Stars). Правила IF/THEN, массовые операции, API для статистики и управления кампаниями, вебхуки и экспорт. Начать бесплатно — 3 дня Pro-триала →
Часто задаваемые вопросы
Есть ли публичный API у Telegram Ads?
Для рекламодателей — нет. На сайте Telegram для разработчиков перечислены Bot API, клиентский API, TDLib, Gateway API и Payments API (проверено в октябре 2026); ни один из них не управляет рекламными кампаниями, а раздел Sponsored Messages предназначен для приложений, которые показывают рекламу. Рекламная платформа ads.telegram.org управляется через веб-интерфейс. ADSLY работает поверх неё через авторизованную сессию.
Как ADSLY подключается к моему кабинету Telegram Ads?
Через сессию Telegram-аккаунта, которому принадлежит рекламный кабинет. Вы подтверждаете запрос в Telegram после ввода номера телефона, пользуетесь браузерным расширением или вставляете токен сессии. Запрос подключает только рекламный кабинет. Так подключаются Euro-, TON- и Stars-кабинеты; кабинеты из Adstat подключаются по логину Adstat.
Насколько защищены мои данные Telegram Ads в ADSLY?
Точки интеграции намеренно узкие. API-ключи только читают, пока вы не включите управление кампаниями, никогда не выводят деньги из кабинета и хранятся хешами; каждое изменение через API остаётся в истории кампании; вебхуки подписываются секретом ключа и уходят только на публичные HTTPS-адреса; write-only URL для трекера может прислать конверсию, но не может ничего прочитать; а на тарифе Agency доступ выдаётся на конкретный кабинет конкретному человеку.
Можно ли выгрузить данные Telegram Ads в Google Sheets?
Прямого коннектора к Google Sheets нет. Выгрузите из панели CSV или Excel и импортируйте его либо читайте API скриптом — /v1/stats отдаёт цифры по каждой кампании за любой период.
Поддерживает ли ADSLY вебхуки для Telegram Ads?
Да. Ключ с Postback URL получает status_change при каждой смене статуса кампании и hourly_digest раз в час с показами, кликами, расходом и действиями по кампаниям. Оба подписаны HMAC-SHA256, а кнопка «Тест» на ключе отправляет ping, чтобы вы проверили свой приёмник.
REST API ADSLY уже доступен?
Да, на тарифах Pro и Agency; ключи вы создаёте сами в панели. Любой ключ читает список кабинетов, кампании, статистику, аналитику, историю кампании и полученные конверсии — 60 запросов в минуту на ключ. Ключ с включённым «Управлением кампаниями» ещё и создаёт, меняет, ставит на паузу, запускает, пополняет, копирует и удаляет кампании и загружает медиа. Документация: adsly.pro/docs/api.
