@retensy/mcp 0.21.2 → 0.24.0

package/skills/rebuild-funnel-from-builder/reference/mapping.md

@@ -0,0 +1,95 @@
+# Таблица сопоставления: другой конструктор → Retensy
+
+Общие понятия, которые есть почти в любом bot-builder'е, и к чему они маппятся в `retensy-bot-graph`.
+Полные конфиги и правила валидатора — в [`../../build-bot-funnel/reference/schema.md`](../../build-bot-funnel/reference/schema.md)
+и [`validation.md`](../../build-bot-funnel/reference/validation.md) — здесь только «куда класть», не дублируем поля.
+
+## Таблица по концепциям
+
+| Концепция в источнике | Узел/конфиг Retensy | Примечания |
+|---|---|---|
+| Точка входа / команда запуска / приветственное сообщение | `TRIGGER_COMMAND` (`/start` и т.п., Telegram/MAX) | Для Instagram входа нет — `TRIGGER_IG_DM`/`TRIGGER_IG_COMMENT`/`TRIGGER_IG_STORY_REPLY`/`TRIGGER_IG_STORY_MENTION` |
+| Триггер по ключевому слову/тексту | `TRIGGER_TEXT` (`matchMode: ANY/EQUALS/CONTAINS/REGEX`) | |
+| Триггер по нажатию инлайн-кнопки (legacy callback без нашего авто-handle) | `TRIGGER_CALLBACK` | Для НОВЫХ кнопок-выборов отдельный триггер не нужен — используй рёбра `btn_N` от `SEND_MESSAGE` |
+| Сообщение / текстовый блок / карточка | `SEND_MESSAGE` (`config.text` + `cards[0]`) | Оба поля обязательны, см. `SEND_NO_TEXT` в validation.md |
+| Сообщение с фото/видео/документом/голосовым/кружком | `SEND_MESSAGE` с медиа-карточкой (`cards[].type`) или `SEND_PHOTO` | Файл заранее через `upload_file`, в графе хранится только URL |
+| Альбом/галерея фото | `SEND_MESSAGE` карточка `type:"gallery"`, `urls[]` | 2–10 картинок |
+| Инлайн-кнопка с выбором (ведёт к ветке сценария) | Кнопка `kind:"CALLBACK"` на `SEND_MESSAGE`, `value:""`, ребро `btn_N` | Непустой `value` ломает переход — см. `validation.md` |
+| Кнопка-ссылка (переход на внешний сайт) | Кнопка `kind:"URL"`, `value` = ссылка; `track:true` если нужно считать клики | Условие по клику — `CONDITION kind:"LINK_CLICKED"` |
+| Вопрос с ожиданием свободного ответа / сбор данных (имя/телефон/email) | `ASK_QUESTION` или `SEND_MESSAGE` с `awaitReply:true` + `saveTo`/`inputKind`/`validator` | Выходы `valid`/`invalid` |
+| Задержка / «подождать N часов/дней» | `DELAY kind:"FIXED"` (`durationSec`) | |
+| Отправка «завтра в HH:MM» | `DELAY kind:"TOMORROW"` | |
+| Отправка в конкретный момент / «через сутки после записи» | `DELAY kind:"UNTIL"` (`isoTimestamp`, опц. `offset`) | |
+| Запуск по расписанию (cron, ежедневная рассылка сводки и т.п.) | `TRIGGER_SCHEDULE` (`cron`, `timezone`) | Headless — без чата, отправка только через `config.target` |
+| Тег / метка подписчика | `ADD_TAG` / `REMOVE_TAG`, условие `CONDITION kind:"TAG"` | `tag` ∈ `[a-z0-9_-]{1,64}` |
+| Переменная / поле подписчика (custom field) | `SET_VARIABLE`, условие `CONDITION kind:"VARIABLE"` | `key` ∈ `[a-z_][a-z0-9_]{0,63}` |
+| Условие «если/иначе» (бинарное) | `CONDITION` (выходы `yes`/`no`) | `match: ALL/ANY` по списку `conditions[]` |
+| Условие со случайным сплитом (A/B тест) | `BRANCH` (`abTest:true`, выходы `case_<id>`) | |
+| Ветвление по значению переменной/коду ответа (больше двух исходов) | `SWITCH` (`expression`, `cases[].value`, выходы `case_<id>`+`default`) | Детерминированный выбор, не случайный |
+| Условие «подписан ли на канал» | `CONDITION kind:"SUBSCRIBED"` | Только Telegram/MAX |
+| Условие по UTM-метке | `CONDITION kind:"UTM"` | |
+| HTTP-запрос / вебхук наружу | Действие `external_request` в блоке `ACTIONS` | Платное действие; своих выходов нет — ветвиться по коду ответа через `saveStatusTo`+`SWITCH` |
+| Входящий вебхук от стороннего сервиса | `TRIGGER_WEBHOOK` (+ `provider`/`connectionId`/`event` для готовых интеграций) | |
+| Оплата / приём платежа | Действие `issue_invoice` в `ACTIONS` (НЕ отдельный узел) | `connectionId` подключения `provider=YOOKASSA`; ветка `paid` — если нужно ждать оплату в диалоге |
+| Триггер «оплата прошла» | `TRIGGER_PAYMENT` | Фильтр `minAmount`/`descriptionContains` обязателен, иначе срабатывает на любую оплату |
+| Форма на сайте / лендинге | `TRIGGER_SITE_FORM` (`siteId`, `formId`) | Только для своего опубликованного сайта в Retensy |
+| Интеграция с CRM (amoCRM, Битрикс24, GetCourse и т.п.) | Действия `amocrm_send`/`bitrix24_call`/`getcourse_send`/... в `ACTIONS` | Нужен `connectionId` из `list_integrations` |
+| Передача диалога оператору / «позвать менеджера» | Действие `agent_chat` в `ACTIONS` | Возврат — `dialog_handoff {active:false}` |
+| AI-ответчик / встроенный GPT-блок | `AI_REPLY` (`mode: "simple"` или `"agent"`) | Платный узел на любом тарифе; у режима `agent` нет выхода `next`, только именованные ветки |
+| Переход в другой сценарий / подворонку | Действие `call_scenario` в `ACTIONS` (`mode: "goto"`/`"call"`) | Ставится последним действием блока |
+| Рассылка по сегменту/тегу | Отдельный инструмент `broadcast_send`, НЕ узел графа | Описание — скилл `send-broadcast` |
+| Конец ветки / «стоп» | Ничего — ветка просто не имеет исходящих рёбер | **Не добавляй** узел `END`, его больше нет в палитре |
+
+## Особенности конкретных источников
+
+Эти сервисы не публикуют документированный формат экспорта воронки/сценария (только список
+подписчиков CSV-экспортом) — поэтому граф почти всегда переносится по скриншотам/пересказу, а не
+по машинному JSON. Ниже — на что обращать внимание при разборе каждого.
+
+- **BotHelp** — сценарии строятся из «блоков» с условными переходами по тегам и триггерам ключевых
+  слов; у BotHelp есть «цепочки» (broadcast-подобные серии сообщений с задержками) — переносятся как
+  последовательность `SEND_MESSAGE` + `DELAY`, а не как единая рассылка. Переменные BotHelp
+  (`{{переменная}}`) — проверь синтаксис конкретных полей (имя/телефон/UTM) и сопоставь с нашими
+  `{{var.*}}`/`{{from.*}}`.
+- **SaleBot** — активно использует HTTP-блоки («Внешний запрос») и JS-код внутри сценария. Код
+  (кастомная логика на JS) не маппится напрямую — спроси пользователя, что конкретно он делает, и
+  реализуй через `external_request`/`FORMULA`/`CONDITION`, либо зафиксируй как немаппируемое.
+- **Senler** — завязан на ВКонтакте (группы, UTM ВК). У Retensy VK — это публикации на стену
+  (`vk_post`), а не полноценный бот-конструктор ВК: диалоговые сценарии Senler ВК переносятся в
+  Telegram/MAX/Instagram-бота Retensy, это не 1:1 перенос платформы, предупреди пользователя.
+- **Leadteh** — похож на BotHelp по модели «блоки + условия по тегам»; отдельно стоит «воронка
+  продаж» (канбан-доска сделок) — это НЕ часть графа сценария, в Retensy ближайший аналог —
+  интеграция с внешней CRM (amoCRM/Битрикс24) через `ACTIONS`, не переноси как узлы графа.
+- **Smartsender** — мультиканальный (email + мессенджеры + SMS); переноси только мессенджер-ветку в
+  граф, email/SMS-рассылки за пределами диалога — отдельный процесс (не маппятся в узлы графа).
+- **ManyChat** — активно использует «Growth Tools» (виджеты входа с разных площадок — Ref URL, Click
+  Widget, Facebook Comments) и условные Smart Delay. Смарт-триггеры входа превращаются в один
+  подходящий `TRIGGER_*` Retensy (чаще `TRIGGER_COMMAND`/`TRIGGER_TEXT`); «Customer Chat» элементы
+  (facebook-специфика) обычно немаппируемы — фиксируй в корзине «не маппится».
+- **PuzzleBot** — конструктор на основе «кубиков» с явными condition-блоками по переменным/рефералам;
+  реферальная система (учёт кто кого привёл) не имеет прямого аналога в Retensy — переносится как
+  `SET_VARIABLE`/`CONDITION` вручную по переменной, зафиксируй ограничение пользователю.
+- **Любой другой источник, не названный выше** — та же методика: инвентарь → сопоставление по
+  смыслу шага (не по названию блока) → немаппируемое в отдельный список на подтверждение.
+
+## Частые ловушки при переносе (из любого источника)
+
+- **Кнопка-выбор с непустым `value`.** В исходнике кнопка часто хранит «значение» (тег/id ветки) —
+  при переносе в CALLBACK-кнопку Retensy это значение **не** переносится в поле `value` (оно должно
+  остаться `""`), переход задаётся только ребром `btn_N`. Если очень нужно явное значение — это
+  отдельный узел `TRIGGER_CALLBACK`, а не кнопка-выбор.
+- **Задержки в других единицах.** Источники часто пишут задержку как «1440 минут» или «1 день» —
+  переведи в секунды (`durationSec`) аккуратно, не копируй число как есть в другое поле.
+- **HTML/markdown разметка текста.** Форматирование источника (жирный/курсив/ссылки) почти никогда
+  не совпадает байт-в-байт с безопасным Telegram-HTML Retensy (`b,strong,i,em,u,ins,s,strike,del,code,pre,a[href],tg-spoiler,br`).
+  Если не уверен, что разметка пройдёт — ставь `parseMode:"PLAIN"` и убери теги.
+  Пустой экран над таблицей выбора кнопок — тоже источник незаметной потери контента, см. п.1 скилла
+  (сначала инвентарь, потом граф).
+- **«Условие» в источнике — не всегда `CONDITION`.** Если исходный блок на самом деле случайно
+  делит аудиторию (A/B) — это `BRANCH`, а не `CONDITION`; если выбирает по значению из списка
+  вариантов — это `SWITCH`. Смотри поведение, не название.
+- **Платные блоки источника vs платные узлы Retensy не совпадают 1:1.** AI-блок / внешний запрос /
+  оплата — в Retensy тоже платные (`PREMIUM_NODE_FORBIDDEN`/`PREMIUM_NODES`) независимо от того,
+  был ли эквивалент бесплатным в источнике — предупреди пользователя при переносе таких блоков.
+- **Не копируй ID узлов источника как ID узлов Retensy.** Нужны валидные UUID (п.4 skill) —
+  генерируй новые, при необходимости сохраняя исходные имена/заголовки в `_title` для трассируемости.