Ця сторінка пояснює, як влаштований граф і як з ним працювати. Вона свідомо не дублює повний перелік типів блоків, полів data, дій і операторів: перелік у коді змінюється часто, а скопійований у документацію — ні. Актуальний перелік завжди віддає машинна довідка DSL (інструмент dsl_reference в MCP). Вона зібрана разом із двигуном і перевіряється автоматично: новий тригер чи дія без рядка в довідці не проходить збірку.
Що таке «воронка — це файл»
У Sviteya воронка не «намальована в редакторі» — вона описана даними. Візуальний редактор, публічний REST API і AI через MCP працюють з однією й тією самою структурою: графом із нод і звʼязків між ними.
Практичні наслідки, заради яких це зроблено:
- воронку можна забрати — отримати граф через API чи MCP і зберегти собі;
- воронку можна зібрати ззовні — скриптом або AI-помічником;
- AI не «підказує», а робить — він працює з тією самою структурою, що й редактор, а не з урізаним набором можливостей;
- редактор і API не розходяться — те, що створене через API, відкривається в редакторі й правиться руками як звичайне.
Структура графа
{
"nodes": [ ... ],
"edges": [ ... ]
}Нода — крок воронки:
{
"id": "welcome_1",
"type": "message",
"name": "Вітання",
"position": { "x": 0, "y": 0 },
"data": { }
}Ребро — звʼязок між кроками:
{
"id": "e1",
"source": "welcome_1",
"sourceHandle": "next",
"target": "delay_1"
}sourceHandle — це вихід ноди. У більшості нод він один (next), у ноди з кнопками — по одному на кнопку, в умови — гілки правил та «Інакше», у рандомайзера — варіанти. Точні назви виходів кожної ноди — у машинній довідці.
Правила, які варто знати до першого запиту
Про ідентифікатори
- Лише латиниця, цифри,
_і-. Без двокрапок і пробілів. До 53 символів - Id кнопок унікальні в межах усієї воронки, решта — у межах своєї ноди
- Якщо надіслати дублікати, сервер тихо їх розведе й перепише ребра — у відповіді може повернутись інший id, ніж ви надіслали
- Id наявних елементів при редагуванні не міняють. На них стоять живі люди, які чекають у воронці: змінили id — і чекання обірвалось
Про публікацію
- У воронці має бути хоча б один тригер
- Повідомлення без тексту і кодове слово без слова публікацію не пройдуть; список усіх блокуючих помилок — на сторінці «Чому воронка не публікується»
- Публікація створює незмінну версію. Двигун виконує останню опубліковану
- Чернетка редагується вільно і на роботу не впливає, поки не опублікована
Про позиції
Розкладайте ноди зліва направо: x через ~380, y через ~300. Якщо позиції збігаються, їх можна впорядкувати кнопкою «Розкласти» в редакторі — основний ланцюжок піде в один ряд, гілки — паралельними рядами нижче.
Категорії нод (карта, не перелік)
Щоб орієнтуватись, з чого взагалі складається воронка. Точні назви типів і поля data — у машинній довідці.
Тригери — те, що запускає воронку. Їх понад тридцять (частина — окремо для Instagram, Messenger і WhatsApp), і вони бувають чотирьох родів:
- дії людини в особистому чаті з ботом:
/start, реферальне посилання, кодове слово, відповідь на все, повідомлення в бізнес-чаті, повідомлення каналу; - зміни стану контакта: додано або знято тег, оплата, досягнутий поріг балів, новий реферал, зміна етапу угоди;
- події в групах і каналах: заявка на вступ, кодове слово в групі, вступ, вихід, коментар, неактивність у чаті;
- зовнішні події: вебінар, вхідний вебхук, розклад.
У клієнтську довідку не потрапляють службові тригери й блоки, зроблені для власних акаунтів сервісу, а публікація не пропускає тригер, недоступний каналу бота.
Крокові ноди — те, з чого будується сам сценарій: повідомлення (у тому числі з очікуванням відповіді), карусель, умова, затримка, дії, рандомайзер, опитування, повтор, бронювання, звіт аналітики, розмова з AI, шаблон WhatsApp, відповідь на коментар Instagram і «Ціль» — фінал, що зараховує результат воронки.
Одна нода «дії» може містити кілька дій поспіль — теги, поля, бали, запуск іншої воронки, HTTP-запит, запис у таблицю, подія в рекламний кабінет, робота з доступом у канал, дії CRM.
Умови працюють за ключем (поле, тег, товар, підписка, вебінар, проєкт, чат, діалог) і оператором (дорівнює, містить, порожнє, більше, куплено, підписаний на канал, дивився ≥ N хвилин, дата пізніше, активність у чаті за N днів і так далі); докладніше про дати — на сторінці «Умови по датах». Повний перелік — у машинній довідці, він регулярно поповнюється.
Дві деталі, які економлять найбільше часу
Квіз не потребує окремої ноди. На старті — запис у поле зі значенням 0, далі кожна кнопка-відповідь додає свою вагу тому самому полю, наприкінці умова розводить за сумою. Так само рахуються калькулятори.
Запуск іншої воронки має точку входу. Дія «запустити воронку» може вказувати, з якого саме тригера цільової воронки починати. Без цього — автоматичний вибір. Якщо вказаний тригер зник із публікації, сервіс відкотиться до автоматичного вибору і запише це в журнал подій, а не мовчки зламається.
Як отримати актуальну довідку
Через MCP. Інструмент dsl_reference. Саме тому в описі інструмента стоїть «читати перед створенням або редагуванням воронок»: AI бере свіжий перелік і не вигадує неіснуючих блоків.
Через API. Самі воронки читаються й записуються тим самим графом: отримати воронку, змінити чернетку, опублікувати, подивитися версії.
Довідка віддається з урахуванням вашого акаунта: блоки, зроблені для внутрішніх потреб сервісу, у клієнтську довідку не потрапляють — щоб AI не пропонував того, що не опублікується. Для точкових змін (додати блок, замінити блок, з’єднати) в MCP є окремі інструменти; змінювати блок краще через replace_node, а повний граф слати лише при створенні воронки.
Рекомендований порядок роботи через API або AI
- Прочитати машинну довідку — вона могла змінитись з минулого разу
- Отримати списки довідників акаунта: боти, теги, поля, товари, вебінари. У графі на них посилаються по id, ніколи по назві
- Створити чернетку з графом
- Відкрити в редакторі й перевірити очима
- Пройти воронку самому в боті (у редакторі є тестовий запуск)
- Опублікувати
- За потреби — повернутись до попередньої версії: історія версій є. Повернути версію можна як опубліковану (тоді чернетка теж стає такою) або лише в чернетку
Пункти 4 і 5 не пропускаються навіть тоді, коли граф зібрав AI. Це не недовіра до інструмента — це та сама перевірка, яку ви робите після себе.
Типові помилки
Посилання по назві замість id. Теги, поля, товари й воронки адресуються тільки по id — це принцип архітектури сервісу, а не примха API.
Зміна id наявних нод. Обриває тих, хто вже йде воронкою.
Публікація без перевірки в редакторі. Граф може бути формально валідним і при цьому робити не те, що ви мали на увазі.
Довіра до старої довідки. Якщо ви скопіювали перелік блоків у свій скрипт місяць тому — він уже неповний.
Типові питання
Чи можна вивантажити свою воронку? Так, граф віддається через API. Це і є те, що ми називаємо «воронка — це файл».
Чи можна імпортувати воронку з іншого сервісу? Ні, формати різні — воронки доведеться перезібрати. Між акаунтами Sviteya воронку можна передати за посиланням: у воронці вмикається перегляд за посиланням і, за бажанням, дозвіл копіювати її в чужий профіль.
Чи відрізняється воронка, створена через API, від зробленої руками? Ні. Це та сама структура, вона відкривається й редагується в редакторі без обмежень.
Чому довідка не продубльована тут повністю? Щоб вона не застаріла. Скопійований перелік розходиться з кодом за тижні; машинна довідка захищена автоматичною перевіркою, яка не дає додати блок у двигун, не додавши рядок у довідку.
Що станеться, якщо надіслати неіснуючий тип ноди? При точкових змінах блоків (додати чи замінити) запит відхиляється з поясненням. Усе, що не проходить перевірку, не дасть опублікувати воронку — див. сторінку «Чому воронка не публікується».
Чи можна редагувати опубліковану версію? Ні, опублікована версія незмінна. Ви правите чернетку й публікуєте наново — саме тому «живе виконання» безпечне.