# Telegram Ads Assistant

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

**Одна система:** навык [`telegram-ads`](skills/telegram-ads/SKILL.md) ведёт запуск (посадочная, каналы, 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». Проверка сохранённых фильтров не доказывает фактическую уникальность охвата.

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

Нужны Google Chrome, аккаунт Telegram Ads и **Node.js 24 или новее** с npm. Установите Node.js с [официального сайта](https://nodejs.org/).

1. Скачайте `telegram-ads-assistant-0.4.0.zip` из [Releases](../../releases) и распакуйте в постоянную папку. Не запускайте из ZIP.
2. Откройте терминал в распакованной папке и выполните:
   ```sh
   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](https://ads.telegram.org/account).
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 или другого совместимого клиента):

```json
{
  "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](skills/telegram-ads/SKILL.md) в каталог скиллов клиента, например `.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-команды

| Задача | Команды |
|---|---|
| Подключение | `extension_status`, `capabilities`, `reload_extension` |
| Локальные пакеты | `validate_package`, `stage_package`, `list_packages`, `get_package` |
| Новый черновик | `prepare_ad`, `read_draft`, `upload_media` |
| Сохранение | `commit_ad` с `operationId` и `expectedFingerprint` |
| Изменения | `prepare_edit` → `commit_edit` |
| Бюджет | `prepare_budget` → `commit_budget` |
| Чтение | `read_account`, `read_ad`, `read_budget`, `read_statistics`, `export_csv` |

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

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

См. [пример пакета](fixtures/example.json). Пример одной записи для `prepare_ad`:

```json
{
  "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.

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

```sh
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](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 до отдельного выпуска.