Дії, які надсилає хід: navigate, handoff, події

Для розробників, у коді: словник дій, які може надіслати хід, — navigate, handoff, власна подія, close_widget, listen — їхні поля, прапорець confirm і що хост робить із кожною.

actions[] ходу — те, що помічник просить хоста зробити. Віджет перетворює кожну на пару DOM-подій (Події) і на деякі діє сам; власний фронтенд читає їх просто з кадру done чи відповіді /message.

Модель Action: type, url, label, source_id, targets[], collect, source, payload{}, confirm. Значущі лише ті поля, які використовує тип.

`navigate`

{
  "type": "navigate",
  "url": "https://shop.example/pricing",
  "label": "Open: Тарифи",
  "source_id": "…",
  "referral_kind": "auto_redirect"
}

Надсилається лише на справжнє рішення: відвідувач наказав («покажи тарифи», у будь-якому режимі навігації), режим помічника auto і сторінка явно пасує, або відвідувач погодився на пропозицію. referral_kind — auto_redirect, suggestion, confirmed, citation — називає пропозицію, і саме його має повторити маячок /followed. З confirm: true це питання: помічник спитав «провести вас туди чи пояснити тут?», хост не має переходити, а наступна відповідь оцінюється як згода чи відмова. Віджет: той самий origin, та сама вкладка, одна за хід, притримується під час голосової відповіді, скасовувана.

Сторінка, яку просто варто відкрити, — не дія: вона приходить у nav_suggestions[] плашкою (≤ 1), і клік на плашку — це вибір відвідувача.

`handoff`

{
  "type": "handoff",
  "collect": true,
  "source": "agent",
  "targets": [
    { "mode": "url", "value": "https://wa.me/380…?text=…", "channel": "whatsapp" },
    { "mode": "email", "value": "mailto:help@example.com?subject=…&body=…", "channel": "email" }
  ]
}

Помічник запропонував людину: targets — посилання власника в порядку власника, кожне з виведеним channel (whatsapp · telegram · viber · email · link) і вже вписаним у посилання питанням; collect каже показати контактну форму в чаті; source — agent (здався) або asked (відвідувач попросив). Хост малює кнопки й форму і повідомляє натиснуте посилання через POST /handoff/opened.

Власна подія

{ "type": "show_products", "payload": { "products": [ … ] }, "suppress_navigate": true }

Подія власника, type — її назва, payload — її поля. Хост її малює; назад нічого не повертається. З confirm: true притримується, доки відвідувач не погодиться. Власні події.

`close_widget` і `listen`

{ "type": "close_widget" } — відвідувач попросив помічника закритися («закрийся», будь-якою мовою). { "type": "listen" } — відвідувач сказав замовкнути і слухати («стоп»); віджет переходить у слухання. Обидві виконує сам віджет; хост лише спостерігає.

`plan` — внутрішня

Притримане натискання з дій на сторінці їде як { "type": "plan", "confirm": true, "page": "/…", "steps": [ … ] }. Вона існує, щоб чіпам згоди й оцінювачу згоди не потрібен був новий механізм; хост ніколи не має її надсилати чи виконувати — сервер застосовує її через міст дій на сторінці на «так» відвідувача.

Прокрутка — не дія

scroll_to_element і scroll_page — обміни моста під час ходу, а не дії на done: для scroll_page віджет надсилає скасовну подію shukai:action:scroll перед прокруткою, щоб хост міг узяти її на себе, але в actions[] нічого схожого на прокрутку не з’являється.

Прапорець `confirm` одним абзацом

Будь-яка дія може нести confirm: true. Це означає: не діяти; показати питання; сервер зберіг пропозицію і оцінить наступну відповідь у будь-яких словах. Чіп згоди віджета сам виконує притриманий navigate (повідомляючи його з kind: "confirmed") або подію; згоду словами сервер відтворює сам; притримане натискання (plan) завжди застосовує сервер. Один хід тримає одну пропозицію: притримане натискання важливіше за тизер події, який важливіший за перенаправлення на сторінку.

Дії, які надсилає хід: navigate, handoff, події

navigate

handoff