Официальный API Telegram Ads: где взять ключ и что он умеет

Рынок уверен, что программно управлять рекламой в Telegram нельзя. Профильное издание пишет это прямым текстом, сервисы автоматизации живут на разборе разметки кабинета, а свежий проект на GitHub прямо в описании называет преимуществом то, что официального рекламного API ему не требуется. Между тем он есть с начала 2024 года, работает на отдельном домене, и ключ к нему лежит в вашем кабинете. Ниже разбираем, у каких кабинетов он есть, что умеет, чего не умеет и на чём спотыкаются все, кто берётся его прикрутить. Всё проверено на живых кабинетах в сентябре 2026 года.

У Telegram Ads есть официальный API?

Есть. Живёт на promoteapi.telegram.org, отвечает JSON, принимает ключ кабинета. Открытый запрос без ключа возвращает отказ ACCESS_TOKEN_REQUIRED, и это единственное, что может увидеть человек со стороны. Публичного анонса не было, документация открывается только авторизованному рекламодателю, в публичной части сайта про него не сказано ни слова. Поэтому рынок о нём и не знает.

«у Telegram Ads еще нет официального API (то есть API есть только у прямых селлеров)» - редакция ppc.world, обзор инструментов автоматизации, июнь 2025

При этом API не заброшен, его правят регулярно. В разделе истории изменений видно, что загрузку фото и видео добавили в августе 2024, таргет на ботов и пиксель в мае 2025, а 18 сентября 2026 года, буквально накануне наших замеров, появилось поле валюты во всех денежных объектах и отдельный метод отправки объявления на проверку. Правда, берёт он только те, что модерацию ещё не проходили: отклонённое ему не отдать.

Где взять ключ и у всех ли он есть

Ключ выдаёт сам кабинет: раздел «Аккаунт», вкладка «API». Там же кнопка копирования, поле ограничения по адресам и кнопка отзыва. Ключ длиной 46 символов, привязан к кабинету, не к человеку, и сам по себе не протухает. В этом его главная разница с сессией браузера, которая умирает от разлогина, смены устройства или просто со временем.

Вкладки может не быть вовсе. По нашей выборке из нескольких десятков клиентских кабинетов она нашлась примерно у двух третей, а у еврокабинетов не нашлась ни разу. Дело при этом не в валюте: сам API работает с евро наравне с TON и Stars, отдаёт валюту в каждом денежном поле. Похоже, вкладку видит владелец организации. Оба еврокабинета, которые мы разобрали подробно, открыты через агентство, и ни один из проверенных нами ключей не проходит проверку на главный аккаунт рекламодателя. Урезанными такие кабинеты при этом не выглядят: настроек в них даже больше, просто это другой тип доступа.

Если вкладки нет, писать в поддержку смысла мало, спрашивайте того, кто выдавал кабинет, видит ли он вкладку у себя. И когда выбираете сервис автоматизации, спросите прямо: а если у моего кабинета вкладки API нет, вы с ним работать сможете?

Отдельно про кнопку отзыва. Она выпускает новый ключ взамен старого, и все интеграции на старом встают молча. Мы у себя запретили её дёргать откуда бы то ни было. И помните, что ключ даёт полный доступ к деньгам: через него можно создать объявление, положить на него деньги с баланса кабинета и снять обратно. Это не токен только для чтения. Хранить как пароль.

Почему его всё время путают с Bot API

Потому что под словами «Telegram Ads API» в выдаче лежат три разные вещи, и нужная среди них не находится. Запрос про подключение токена приводит к статьям про токен от BotFather, вопросы на технических форумах про рекламный кабинет оказываются вопросами про ботов, а по самому запросу в топе оказывается раздел документации про отрисовку рекламных сообщений внутри клиентов Telegram.

Что через него можно делать

Чтение закрывает почти всё, что нужно закупщику: список объявлений до сотни за запрос вместе с таргетингом, баланс кабинета, статистика по объявлению и по кабинету, справочники языков, тем и стран. Причина отклонения приходит прямо в списке, а в интерфейсе за ней нужно открывать карточку каждого объявления по очереди. На одном кабинете такой запрос принёс нам девятнадцать причин отказа там, где обычный путь не принёс ни одной.

Запись умеет ставку, паузу, лимит расхода, название, пополнение и снятие бюджета, создание, удаление и загрузку баннеров. Ключ идемпотентности передаёте вместе с запросом, и повтор того же запроса вернёт тот же результат вместо второго объявления. Ответ живёт сутки, а тот же ключ с изменёнными параметрами отвечает отказом, то есть подменить запрос незаметно не получится. Для массовой заливки это буквально страховка от дважды залитой пачки, которой у формы в кабинете нет вовсе.

Ещё две мелочи, которые экономят время. Созданное объявление сразу возвращает свой идентификатор, и его не надо искать по названию в списке. А баланс приходит разложенным на три числа: сколько денег свободно, сколько потрачено и сколько лежит на бюджетах объявлений. Последнего в интерфейсе нет, хотя это ровно ответ на вопрос, где деньги, если на балансе их нет.

Чего он не умеет

Текст объявления через API не меняется. Метод отвечает, что всё прошло, возвращает объект объявления, а текст остаётся прежним. Мы проверили четырьмя способами: на активном объявлении и на остановленном, дописывая метку в конец строки и в начало. Результат один и тот же. Ссылку поменять тоже нельзя, но тут хотя бы честный отказ отдельным кодом. Параметра таргетинга у метода правки нет вовсе.

Подобрать площадки через API не получится: есть только точное разрешение имени канала, а поиска по названию и похожих каналов нет. Нет и подсказок поисковых фраз. И API не знает, какие поля есть у формы вашего конкретного кабинета, хотя кабинеты между собой заметно различаются.

Надежду «где-то есть недокументированные методы» мы закрыли экспериментом: перебрали 32 имени, включая все приватные методы, которыми пользуется сам интерфейс кабинета. Все до единого ответили «неизвестный метод», ровно как заведомо выдуманное имя. Скрытого слоя нет, документация полная.

Почему правки через API не роняют объявление в модерацию

Через интерфейс полная правка активного объявления снимает его с открута и возвращает в очередь проверки. Через API ставка, пауза, лимит расхода и название меняются без этого: мы смотрели статус сразу, через пять секунд и через минуту на четырёх живых объявлениях с деньгами, перехода в проверку не было ни разу.

Причина обескураживающая. Перемодерации нет потому, что менять модерируемое API просто не даёт. Текст не меняет, ссылку отвергает, таргетинга у метода правки нет. Через API меняется всё, что не видит зритель объявления, и не меняется ничего из того, что он видит. Если вам нужно поправить текст работающего объявления, это по-прежнему означает повторную проверку и паузу в открутке.

Главная ловушка: отказ приходит с кодом 200

Кодов 401 и 403 этот API не отдаёт вовсе. Мусорный ключ, пустой ключ, превышение частоты запросов, несуществующий метод - всё приезжает с обычным успешным кодом ответа и телом, где написано, что всё плохо. Проверено шестью запросами подряд. Любая связка, которая судит об успехе по коду ответа, а так делают почти все быстрые сценарии в конструкторах автоматизации, будет считать отказ успехом и рапортовать «готово».

Незнакомые параметры API глотает молча: отправили выдуманное поле, получили в ответ подтверждение и полное игнорирование. Простое правило: «принял» не равно «сделал». Ровно так можно месяцами думать, что шлёшь исключение в таргетинге, которое на деле никуда не уходит. Единственная защита - перечитывать объявление отдельным запросом после каждой правки и сверять, что применилось.

Опечатка в имени денежного поля денег не двигает. Мы отправляли неправильные имена обоих денежных параметров, оба были проглочены без последствий. Случайно не спишете. Но и не положите: сервис отрапортует, что всё хорошо.

Что обманывает в статистике

Обманывают тут две вещи: поле подписок, которое уже посчитано в действиях, и нули, которые выглядят как данные. Но сначала про то, ради чего сюда вообще стоит идти. Пятиминутные срезы Telegram хранит минимум 343 дня: мы забрали пятиминутную ленту у объявления, созданного в октябре 2025 года, и она сошлась с дневной точкой без расхождений. Границу, за которой пятиминутка кончается, найти не удалось, уперлись в возраст самих объявлений. То есть историю можно забрать задним числом, и день, когда ваш трекер лежал, перестаёт быть дыркой в отчётах.

В каждой точке рядом с действиями приходит поле подписок на канал. Выглядит как отдельная метрика, но это то же самое число под старым именем: весной 2025 поле переименовали, а прежнее оставили работать для совместимости. Сложите одно с другим, и конверсии всей рекламы каналов удвоятся, а экономика связки будет выглядеть вдвое лучше, чем есть. Второе: лента точек сплошная, простой приезжает нулями. За шесть часов тишины приходит ровно семьдесят две нулевые точки. Текущий незакрытый час тоже добивается нулями до полного. Мы на этом обожглись: вспомогательная проверка, считавшая час закрытым по числу точек, была неверной, и её пришлось убрать.

Что до точности самих цифр, мы сверяли их со своими замерами перед переходом. Дневные суммы сошлись копейка в копейку, итог кабинета за неделю на сотнях тысяч показов разошёлся на ноль процентов, часовые срезы на одну десятую, и та разница объяснялась нашим собственным округлением на границе часа.

Денежные поля названы не так, как вы думаете

У объявления два денежных поля, и оба названы обманчиво. «Начальный бюджет» - это то самое верхнее число колонки бюджета, которое в интерфейсе все зовут дневным: сумма, которая списывается с баланса кабинета на объявление. А «дневной лимит» на нашей практике работает как потолок расхода на всё время, где ноль означает «без лимита», хотя документация описывает его как суточный. Расхождение неприятное, и проверять стоит на своём кабинете.

Перепутать их дорого, и мы это проходили: наше копирование какое-то время слало дневную сумму в оба поля, и потолок расхода оказывался равен дневному бюджету. Копии исправно умирали через сутки. Нативное копирование в кабинете лимит не наследует, и это правильное поведение. Минимальный дневной бюджет, к слову, всё тот же: единица в валюте кабинета, меньше форма кабинета не принимает. Через API объявление с нулевым бюджетом создаётся, только крутиться оно не начнёт.

Что это меняет для закупщика

Если вы не пишете код, меняется надёжность инструментов, которыми вы пользуетесь. Сессия кабинета перестаёт протухать посреди ночи, статистику отдаёт сам Telegram, в списке видно настоящие названия целей, которых в интерфейсе нет. Мы в Zaliv перевели на официальный ключ чтение списков и статистику в сентябре 2026. На момент публикации ни один кабинет не пришлось откатывать на старый путь.

Отдельная история - деньги, запертые в остановленных и отклонённых объявлениях. Вернуть остаток на баланс можно и через интерфейс, но по одному объявлению за раз, поэтому до этого обычно не доходят руки. Когда мы впервые посчитали, сколько лежит в некрутящихся объявлениях по всем кабинетам разом, сумма оказалась сопоставима с бюджетом небольшой кампании. Через API это собирается одним проходом.

Чего это не меняет: подбор площадок, правку текстов и особенности конкретного кабинета API не покрывает. Поэтому любой серьёзный инструмент всё равно ходит двумя путями, а фраза «мы полностью на официальном API» на практике означает, что чего-то сервис не умеет. Это, кстати, хороший вопрос на демо любого сервиса.

Что об этом говорит пользовательское соглашение

Прямого запрета управлять своим кабинетом программно в публичных документах Telegram нет. Правила размещения посвящены содержанию объявлений, слов про API, скрипты и расширения там нет вовсе. Единственный документ, который касается темы, это условия рекламной платформы, и формулировка там узкая.

«not permit any third party to put forward a bid at an Auction using its Account» - Telegram Ad Platform Terms of Service, пункт 3.3(e), ads.telegram.org/tos

Речь про то, чтобы не давать третьему лицу делать ставки от имени вашего аккаунта. Свой ключ, выданный вам самим Telegram, и чужая сессия в чужих руках выглядят по-разному, но грань здесь тонкая, и каждый проводит её сам. Ответственность за сохранность доступа и за действия неуполномоченных лиц лежит на рекламодателе, а любой сервис посередине остаётся вашим подрядчиком без полномочий площадки. То есть за всё, что сделано вашим ключом, отвечаете вы.

Как это устроено у соседей

Закрытый доступ к рекламному API сам по себе нормален: заявку и модерацию приложения требуют все крупные площадки. Telegram отличается другим - у него закрыта не дверь, а описание двери. Прочитать, что умеет API, нельзя, пока не окажешься внутри кабинета, которому его дали.

Забавный побочный эффект: получить ключ в Telegram быстрее, чем где бы то ни было, а узнать о его существовании сложнее всего. Если у вашего кабинета вкладка API есть, вы уже держите в руках то, чего, по мнению рынка, не существует. Посмотреть, как это выглядит в работе, можно в демо без регистрации.

Источники

Все проверки проводились на живых кабинетах 19-21 сентября 2026 года. Кабинет Telegram Ads меняется без анонсов, поэтому сверяйтесь с датой.

• promoteapi.telegram.org - сам API, отвечает на запрос без ключа
• ads.telegram.org/getting-started и /guidelines - официальная справка и правила размещения
• ads.telegram.org/tos - условия рекламной платформы, пункт 3.3(e) про третьих лиц
• core.telegram.org/bots/api и core.telegram.org/api/sponsored-messages - два других API, с которыми путают
• ppc.world - обзор инструментов автоматизации, июнь 2025
• Google Ads API, Meta Marketing API - для сравнения с соседями