Telegram Ads API: где автоматизация закупки обрывается

У Telegram Ads есть официальный API: promoteapi.telegram.org, 45 методов, журнал изменений с 29 января 2024 г.. Ключ выдаётся в аккаунте Telegram Ads, в настройках, и дальше документация обещает, что «any requests to the API can be executed». Других условий она не ставит. Всё, что ниже, снято со снимка страницы ads.telegram.org/docs/api от 20 сентября 2026 г..

Значит ставку, паузу, бюджет объявления, отправку на модерацию и съём статистики можно вести без кабинета. Пополнение кабинета вести так нельзя, и это единственная граница, из-за которой закупка остаётся частично ручной. Этот разбор мы держим потому, что через те же методы работает наш MCP-сервер.

TGAdsMCP - MCP-сервер для этого API: ваш ИИ-агент читает статистику и ведёт кампании сам, без парсера кабинета. Тарифы и подключение.

curl -i https://promoteapi.telegram.org/getCurrentAccount

HTTP/1.1 200 OK
{"ok":false,"error":"ACCESS_TOKEN_REQUIRED"}

Одна ловушка видна уже здесь: отказ в авторизации приходит с 200 OK, кодов 401 и 403 в ответах нет, и ветвиться приходится на поле error в теле. Ответ всегда JSON-объект с булевым ok: при true нагрузка лежит в result, при false причина строкой в error. Замеры наши, 20 и 23 сентября 2026 года. Имя метода так не проверить: выдуманное возвращает то же тело.

Ads API не имеет отношения к Bot API: другой хост, другой токен, другие объекты, и строка api.telegram.org встречается в документации Ads API ровно дважды - оба раза хвостом promoteapi.telegram.org, то есть сам по себе этот хост в ней не назван. Под тем же названием ищут ещё два интерфейса Telegram: core.telegram.org/api/sponsored-messages нужен тому, кто пишет клиент мессенджера и показывает в нём спонсорские сообщения, а core.telegram.org/api/revenue - про доход владельца канала или бота. Рекламодателю нужен третий, тот, что здесь.

Что API ведёт вместо человека#

Порядок документации сам идёт доменными блоками. Третья колонка - то, чего в этой области нет, и именно она решает, где придётся оставить руки.

Пауза и возобновление живут в editAd, флагом is_paused; там же меняются cpm и daily_budget_limit. Отдельный editAdStatus документация держит устаревшим и оставила в нём одну строку с этой же отсылкой, так что готовый пример из чужой статьи годичной давности стоит проверить по имени метода.

Съём статистики упирается в одно правило: шаг ровно 300 или 86400 секунд и период не длиннее 1000 интервалов. При суточном шаге это 1000 дней, при пятиминутном - около 3,5 суток, так что год пятиминутной детализации собирается примерно из ста запросов.

Деньги: что API двигает и чего не приносит#

Деньги внутри кабинета двигают четыре метода: между главным аккаунтом и связанным, между бюджетом аккаунта и бюджетом объявления. Плюс initial_budget в createAd, который делает то же в момент создания. Ни один из 45 методов не заводит деньги извне. Внешние деньги существуют в API только как тип контрагента транзакции - external, доступный на чтение, с необязательным комментарием вроде номера счёта. Пополнение остаётся ручной операцией, и именно на ней автоматизация закупки обрывается.

Переводы между аккаунтами асинхронны: возвращается TransactionStatus со статусом in_progress, failed или completed, и опрашивать его приходится через getTransactionStatus, потому что вебхуков в API нет.

Цену креатива в показах документация называет сама, и это три числа, которые стоит знать до первой ставки. Объявление с фото требует в среднем на 50-80% более высокого CPM, чтобы показываться, с видео - на 70-100%, с аватаркой канала (show_userpic) - на 30%. Минимальный CPM при этом программно не получить: ни поля, ни метода, ни текста ошибки, при том что cpm в createAd обязателен.

Токен: где взять и что он открывает#

Токен выдаёт страница ads.telegram.org/account/api, она открывается после входа в кабинет. В самой документации этого адреса нет, это наше наблюдение. Передают токен в каждом запросе заголовком Authorization: Bearer <token> либо параметром access_token.

curl -s https://promoteapi.telegram.org/getCurrentAccount \
  -H "Authorization: Bearer $TGADS_TOKEN"

Документация обе формы уравнивает, а слово access_token упоминает один раз мимоходом. Утечку создаёт одна из четырёх форм параметра - строка запроса URL: она попадает в логи прокси, в историю оболочки и в Referer. Остальные три формы - это тело запроса, там токен не виден. Заголовок стоит выбирать потому, что с ним выбор формы тела вообще ни на что не влияет.

Цена утечки выше, чем кажется. Утёкший ключ - это утёкший кабинет: его статистика, объявления, ставки и бюджет. До соседнего кабинета он не достаёт - там нужен свой ключ, и getRelatedAccountsList на обычном кабинете отвечает MAIN_ACCOUNT_REQUIRED. Отзыв в настройках аккаунта мгновенный, старый токен умирает сразу, новый выдаётся вместо него, и окна, где работали бы оба, нет. Это наблюдение из интерфейса, в документации отзыва нет вообще.

Что подключается этим ключом

Где документацию легко прочитать неправильно#

Четыре места стоит знать до того, как валидатор начнёт отвергать верные значения.

У createAudience поле title ограничено «1-64 символа», у editAudience - «1-64 байта»; та же пара у createPixelEvent и editPixelEvent. Для кириллицы это расходится вдвое: 64 кириллических символа в UTF-8 занимают до 128 байт, поэтому название, принятое при создании, может не пройти при переименовании. У объявления так не выйдет, там title в байтах в обоих методах.

У text в createAd в колонке «Required» стоит «Optional», а описание той же строки требует его для всех типов таргетинга, кроме поиска. У placement случай обратный: в колонке «Yes», в описании «currently optional», и при отсутствии значение выводится из target.type. Передавайте оба явно.

createPixelEvent принимает type из 19 значений, а объект PixelEvent возвращает его из 20. Лишнее - ровно landing_view, событие, которое платформа создаёт сама. Валидатор, собранный по списку createPixelEvent, отвергнет корректный ответ API: собирать его надо по PixelEvent.

И про валюту. В кабинете она называется «Граммы», а код в самом API остался TON. Сопоставление по отображаемому имени сломается при первом переименовании в интерфейсе.

Чего в документации нет, и чем это оборачивается#

• Лимиты запросов, квоты и код 429. Слова «rate limit», «quota», «throttling» и число 429 не встречаются на 2 458 строк ни разу. Ретраи, выдержку и очередь придётся спроектировать самому и проверить опытом.
• Каталог ошибок. На весь документ приходится 6 строк ошибок: AD_TITLE_REQUIRED, IDEMPOTENT_PARAM_MISMATCH, IDEMPOTENT_REQUEST_IN_PROGRESS, CHANNEL_ID_UNKNOWN, BOT_ID_UNKNOWN, NOT_ENOUGH_BUDGET. Полного списка значений error нет, поэтому обработчику нужна ветка «строка, которой мы раньше не видели».
• Вебхуки и песочница. Ни того, ни другого: состояние узнаётся опросом. Репетиция при этом возможна, и это наш вывод из двух её собственных фраз: initial_budget по умолчанию 0, а на модерацию объявление уходит само только при непустом бюджете, так что объявление с нулевым бюджетом создаётся и читается, никуда не уходя.
• Версионирование. Ни сегмента версии в URL, ни заголовка. Обратную совместимость документация упоминает трижды и дважды предупреждает, что поведение может измениться, но ни сроков, ни определения ломающего изменения нет.

Повторный запрос не создаёт второе объявление, если послать ключ: заголовок Idempotency-Key: <key>, до 128 символов, сохранённый ответ живёт сутки и приходит с пометкой Idempotent-Replayed: true. Ключ принимают 9 методов из 45: все создающие и все четыре переноса денег. editAd в их число не входит, хотя меняет ставку и дневной лимит, так что безопасный повтор правки после таймаута остаётся на клиенте.

Эти методы - из вашего ИИ-агента#

TGAdsMCP - это MCP для Telegram Ads. Подключается к вашему ИИ-клиенту одним адресом, и дальше агент работает этими же методами: создаёт объявление, правит ставку, ставит на паузу, снимает статистику за период, который API принимает. Работает он по документированному API, поэтому парсер кабинета здесь не участвует, а ловушки выше разобраны внутри, а не оставлены вам на встречу.

Есть два других пути, и их стоит назвать. Первый - MCP, который водит веб-интерфейс вашими cookie входа: Free-cat/telegram_ads_mcp, zai-one/telegram-ads-mcp, NikitaZhidkov/tg-ads-mcp на GitHub. Чего это стоит, сказано в их собственной документации, а не в нашей: сохранённый файл сессии «is equivalent to your login credentials for ads.telegram.org - anyone with it can act as you, including spending your TON ad budget», а сами cookie - «the equivalent of an unscoped login», обращаться с ними следует «like passwords» и никогда не вставлять в чат. Мы берём вместо этого API-ключ именно потому, что он - противоположность неограниченному: открывает один кабинет, в котором выпущен, не несёт пути ни к переписке, ни ко входу в Telegram, и отзываете вы его сами, одним нажатием.

Второй путь - собрать самому, и отправная точка для этого хорошая: telead на PyPI покрывает все методы этой документации, с ключами идемпотентности, повторами и постраничным выводом. Чем он не является - так это сервером. Ваш ИИ-клиент подключается к адресу, а не к pip-пакету, поэтому остаётся работа, которая не кончается: написать слой MCP, где-то его держать, не давать ему засыпать, когда вас нет за машиной, и править свой код каждый раз, когда API двигается. Взамен ключ остаётся на вашем диске - и это настоящая разница, которую стоит взвесить: у нас он хранится на нашей стороне, и что это значит написано, а не подразумевается.

Кабинеты отвечают в одном разговоре: в GRAM ключ доступен каждому, кому открыт кабинет, а кабинет в евро своего раздела Ads API не имеет и ведётся агентским ключом, под которым заведён. Каждое изменение агент сначала показывает, а спрашивает вас ваш ИИ-клиент - до отправки. Дневной потолок расхода ставится на объявлении: у нового его нет, если не задать.

И одно, чего своим парсером не закрыть: Telegram меняет API без предупреждения - запись от 18 сентября 2026 г. это уже показала, переходного окна у неё не было. За изменениями следим мы, а у вас в ИИ-клиенте остаётся тот же один адрес.