Telegram Ads Assistant

Методика рекламы в этом репозитории собрана по материалам Марии Смирновой и её канала Маша & Russian Ads (раньше — «Маша & Telegram Ads»). Маша — редкий практик официальной Telegram Ads, у которого разборы каналов, 1к1, исключений, тестов и экономики можно сразу нести в кабинет. Если ведёте рекламу всерьёз, её канал стоит читать раньше чужих чек-листов. Это рабочий свод её подходов, не дословный курс и не замена публикациям.

Одна система: навык telegram-ads ведёт запуск (посадочная, каналы, 1к1, тесты, оптимизация) и тем же маршрутом создаёт и правит объявления в кабинете. Расширение Chrome, локальный мост и MCP — руки этой системы. Агент не должен сначала «применить методику», а потом отдельно «открыть приложение».

Русский интерфейс. Не требует BB, отдельного VPS или официального рекламного API. Вы описываете объявление структурированными данными; расширение заполняет форму Telegram Ads в авторизованном Chrome, загружает медиа и сохраняет запись. Агент сверяет сохранённые настройки.

Версия приложения 0.5.0, навыка системы 0.6.0. Это независимый инструмент, не продукт Telegram. Он использует DOM кабинета; изменения сайта могут потребовать обновления адаптера.

Что умеет

• Создавать объявления Search, Bots, Channels и Users.

• Выбирать несколько каналов, страны и языки; задавать исключения площадок и аудиторий.

• Загружать JPEG, PNG и MP4 из локального файла или HTTP(S)-ссылки, включая localhost.

• Читать объявления, CPM, бюджеты, статусы и отображаемую статистику; скачивать доступный CSV.

• Подготавливать и сохранять изменения текста, URL, CPM, статуса и бюджета.

• Вести запуск по одной методике: бриф, каналы, креативы, матрица тестов, исключения, журнал оптимизации.

• Работать через MCP: проверка → подготовка → сохранение → чтение результата.

• Обновлять уже установленное расширение командой MCP reload_extension.

Проверено в реальном кабинете: создание четырёх типов, включение статуса, фото, видео, 10 каналов с двумя исключениями, Users с тремя включёнными и двумя исключёнными аудиториями, Search с тремя запросами, размещение Users «Banner in Video». Проверка сохранённых фильтров не доказывает фактическую уникальность охвата.

Related MCP server: telegram-ads-mcp

Установка за несколько минут

Нужны Google Chrome, аккаунт Telegram Ads и Node.js 24 или новее с npm. Установите Node.js с официального сайта.

1. Скачайте telegram-ads-assistant-0.4.0.zip из Releases и распакуйте в постоянную папку. Не запускайте из ZIP.

2. Откройте терминал в распакованной папке и выполните:

   npm ci
   npm start

   Дождитесь сообщения Telegram Ads bridge listening on loopback port 18791. Оставьте терминал открытым. На macOS после установки зависимостей можно запускать Start.command двойным щелчком.

3. Откройте в Chrome chrome://extensions/, включите «Режим разработчика», нажмите «Загрузить распакованное расширение» и выберите папку, где лежит manifest.json.

4. В этом же профиле Chrome войдите в Telegram Ads.

5. Нажмите значок расширения. Откроется панель со списком объявлений. Кнопка обновления перечитывает кабинет; индикатор MCP показывает связь с локальным сервером.

Первый запуск создаёт ваш собственный ключ соединения в .local/bridge.json и src/local-config.js. Эти файлы не входят в релиз. Не отправляйте их другим людям. Не публикуйте рабочую папку целиком после запуска.

Если не работает

• Нет соединения: проверьте, что npm start работает, порт 18791 свободен и панель расширения открыта. Нажмите кнопку подключения MCP.

• Пустой список: войдите в нужный профиль Telegram Ads и нажмите обновление. Список отражает загруженные строки, не весь исторический архив.

• Не запускается Start.command: выполните npm start в терминале.

• После переезда папки: заново выберите её в Chrome и обновите абсолютный путь в MCP-клиенте.

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

Подключение AI-агента

Добавьте в настройки MCP вашего клиента (Claude Code/Desktop, Cursor, Codex или другого совместимого клиента):

{
  "mcpServers": {
    "telegram-ads-assistant": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/telegram-ads-assistant/server/mcp.js"]
    }
  }
}

На Windows используйте абсолютный путь с / либо экранированными \\. Если клиент не видит node, задайте полный путь к исполняемому файлу. MCP запускает stdio-сервер, но не заменяет отдельный npm start. Chrome и панель расширения должны оставаться открытыми.

Скопируйте папку skills/telegram-ads в каталог скиллов клиента, например .claude/skills/, .agents/skills/ или .bb/skills/. Это единственный рабочий вход: план и кабинет. Старые имена telegram-ads-method и telegram-ads-assistant оставлены как указатели на него. Если клиент не поддерживает скиллы, добавьте skills/telegram-ads/SKILL.md к инструкции агента.

Пример поручения на систему целиком:

Подготовь запуск Telegram Ads для [продукт]: посадочная, 8 каналов, тест креативов на общем пуле, затем 1к1. Бюджет тестов [сумма], цель [действие]. Когда матрица готова — проверь кабинет через Assistant, собери пакет, покажи перед сохранением. После разрешения создай объявления on hold и верни ID.

Пример только на кабинет:

Проверь подключение и выбранный кабинет. Подготовь одно объявление моего бота на эти три канала с бюджетом 1 и CPM 0.2. Покажи параметры перед сохранением. После разрешения сохрани, повторно прочитай объявление и сообщи его ID и статус. Бюджет автоматически не пополняй.

Основные MCP-команды

stage_package хранит пакет локально, не создаёт рекламу. Импорт файла в панели также не равен публикации. Для полного агентского сценария используйте MCP. Старые prepare_form и get_statistics оставлены для совместимости; для новой работы используйте prepare_ad и read_statistics.

Формат объявления

См. пример пакета. Пример одной записи для prepare_ad:

{
  "ad": {
    "id": "demo-channels-1",
    "title": "demo-channels-1",
    "text": "Ваш проверенный рекламный текст.",
    "url": "https://t.me/ExampleBot?start=demo_1",
    "budget": 1,
    "cpm": 0.2,
    "status": "on_hold",
    "target": {
      "type": "channels",
      "channels": ["example_channel", "second_channel"],
      "excludeChannels": ["excluded_channel"]
    }
  }
}

Замените демонстрационные имена реальными. Ставка должна соответствовать минимуму текущего кабинета. Уточняйте валюту и надбавки за медиа перед сохранением.

• Search: {"type":"search","queries":["ваш запрос"]}. Только простой URL бота без start, без загружаемого медиа.

• Bots: {"type":"bots","bots":["ExampleBot"]}. Площадка должна удовлетворять порогу Telegram (в проверенном кабинете 1000+ daily users). Произвольного медиавложения нет.

• Users: {"type":"users","countries":["Germany"],"languages":["Russian"],"channels":["example_channel"],"excludeChannels":["excluded_channel"]}.

• Для Users placement — channel_post или video_banner; второй режим означает размещение в чужом видео, не загрузку вашего ролика.

• В Channels excludeChannels исключает площадки. В Users исключает аудитории каналов. Это разные механизмы.

• Названия стран/языков/тем задаются точно как в английском кабинете; username без @. Таргетинг сохранённого объявления неизменяем.

Медиа: upload_media({"path":"/path/ad.mp4"}) либо upload_media({"url":"https://example.com/ad.mp4"}). Ровно один источник. Для существующего объявления добавьте adId. Локальный кэш ограничен 200 MB, файл видео — 20 MB, изображения — 5 MB. Это консервативные пределы приложения. URL должен отдавать сам файл, а не HTML-страницу просмотра. Private LAN и metadata endpoints отклоняются; localhost относится к машине сервиса.

Ограничения и внешние действия

• Публикация и бюджетные команды включены. Агент должен действовать в рамках разрешения владельца и согласованного лимита.

• commit_ad автоматически отмечает галочку условий Telegram. Разрешение на их принятие должно быть получено у владельца до вызова команды.

• submitted_needs_verification — отправка формы, не доказательство успеха. Требуется чтение сохранённого объявления.

• Автоматическая сквозная сверка результата пока не завершена: её выполняет вызывающий агент.

• delete_ad открывает подтверждение удаления; окончательное удаление не реализовано. clone_ad открывает черновик копии. Расписание реализовано как подготовка и не прошло полную живую приёмку.

• Изменение/возврат бюджета покрыты адаптером и тестами, но полный живой цикл всех финансовых операций не заявляется.

• Графики canvas не извлекаются. CSV и таблицы зависят от доступности в кабинете; нужный месяц следует проверить на странице.

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

• Внешнего публичного вебхука и долговечной очереди нет. Локальный HTTP-мост слушает только 127.0.0.1, требует ключ и не должен публиковаться в интернет напрямую.

• Расширение не пополняет аккаунт, не подключает кошельки и не обходит ограничения Telegram.

Разработка и выпуск

npm ci
npm test
python3 scripts/package_release.py

Исходники расширения: src/, index.html, style.css, manifest.json; серверы: server/; тесты: tests/. JS-модули исполняются непосредственно Chrome: отдельная компиляция расширения не нужна. ZIP содержит готовый код расширения и локального сервера; npm-зависимости устанавливаются на машине пользователя через lockfile.

Скрипт выпуска включает только разрешённые файлы, исключает локальные ключи, данные и node_modules, создаёт SHA-256. Он не публикует релиз сам.

Проверки входа

Подробный контракт: VALIDATION.md. read_constraints читает доступные лимиты кабинета. validate_package возвращает человекочитаемые ошибки и структурированные issues; serverValidationRequired всегда отделяет локальную проверку от серверной.

Валюта, посадочная и география (0.5.0)

Пакеты принимают currency: "TON" | "EUR" | "XTR" (Stars). Перед заполнением валюта сверяется с read_constraints; неизвестная валюта или несовпадение останавливают подготовку. Конвертации сумм нет. MCP: prepare_ad({ad, currency: "XTR"}). Устаревший prepare_form отключён; используйте prepare_ad.

URL может быть HTTPS-сайтом (UTM сохраняются), t.me каналом, постом, invite или ботом с необязательным start. Search требует простой Telegram URL. Синтаксическая проверка не означает доступность назначения в аккаунте. Для сайта подготовка ждёт нативное поле имени сайта; при отказе Telegram прекращается. websiteName задаёт подпись сайта. Перед commit проверяйте errors, URL и fingerprint. География определяется выбранными странами и сообщением кабинета, а не валютой.

14.09.2026 в Stars-кабинете SelfyStudio проверено без создания рекламы: внешний сайт отклонён сообщением You can't promote external links; Users → Russian Federation принят с Will be shown for users from Russian Federation. Это наблюдение конкретного кабинета, не универсальная матрица прав. Украина и остальные страны отдельно не проверены; ограничения TON не переносятся на Stars. EUR также не означает запрет сайта: возможности зависят от кабинета и провайдера.

Локальная рабочая установка обновлена; ZIP старого релиза выше остаётся 0.4.0 до отдельного выпуска.