Маячки, передача і передача розмови
Для розробників, у коді: POST /followed і /handoff/opened — два маячки, що рахують результати; POST /handoff — заявка; GET /conversation — продовження чату між сайтами одного сімейства.
Чотири маленькі ендпоінти завершують те, що почав хід. Два з них — маячки: вони завжди
відповідають 204, хай би що сталося, бо надсилаються, поки сторінка вивантажується, і нічого не
розкривають. Усі чотири несуть ключ віджета в тілі чи заголовку, і Origin усе одно
перевіряється.
POST /followed — відвідувач пішов туди, куди вказав помічник
Надсилається через navigator.sendBeacon у момент переходу (кадр WebSocket програв би гонку з
вивантаженням) і при кліку на цитату.
{ "widget_key": "wk_…", "conversation_id": "…", "url": "https://…/pricing", "kind": "suggestion" }kind називає пропозицію, на яку відповідає перехід, — auto_redirect, suggestion,
confirmed, citation — і має з нею збігатися: перехід, зарахований під іншим видом, потрапляє в
іншу комірку і читається як нуль переходів. Перехід може лише збільшити наявну пропозицію і
ніколи її не перевищити, тож відсоток на сторінку чесний, і ніхто не може створювати рядки. Завжди
204: хибне тіло, невідома розмова, ліміт частоти (120 на хвилину) — усе мовчки.
POST /handoff — відвідувач лишив контакт
fetch, а не маячок — у нього є результат, на який відвідувач чекає.
{
"widget_key": "wk_…",
"conversation_id": "…",
"code": "default",
"contact": "olena@example.com",
"comment": "Дзвоніть після 18:00",
"source": "asked"
}| Поле | Сенс |
|---|---|
contact |
пошта або номер телефону; вид визначається, а не обирається |
comment |
необов’язковий, до 5 000 символів |
code |
віджет — щоб заявка з меню «Зв’язатися з нами» без розмови все одно знайшла помічника |
source |
agent (помічник здався), asked (відвідувач попросив), menu (кнопка) |
| Статус | Сенс |
|---|---|
200 { "ok": true } |
збережено: контакт зашифровано, питання зафіксовано; власник отримує лист після коміту, а інструмент доставки, якщо заданий, викликається у фоні |
422 "unrecognised_contact" |
не пошта і не телефон — віджет перепитує |
404 |
розмова не цього сайту |
429 |
понад 30 на хвилину |
POST /handoff/opened — відвідувач натиснув кнопку переходу
Маячок для натиснутої кнопки WhatsApp / Telegram / Viber / пошти: без нього власник, чия єдина ескалація — посилання, бачив би нуль передач вічно.
{
"widget_key": "wk_…",
"conversation_id": "…",
"code": "default",
"source": "agent",
"channel": "whatsapp"
}Канал звіряється з цілями самого помічника, а не береться на віру; невідомий канал
зараховується під один із налаштованих (перший за абеткою). Завжди 204.
GET /conversation?token=… — продовження між сайтами одного сімейства
localStorage не перетинає origin. Коли помічник переходить на сторінку іншого origin зі списку
того самого ключа віджета, рантайм додає ?sa-conversation=<токен>; віджет на місці призначення
обмінює його раз:
GET /conversation?token=…
X-Widget-Key: wk_…200 { "conversation_id": "…", "messages": [{ "role": "user" | "assistant", "text": "…" }] } —
недавній текст розмови, до 50 повідомлень. 400 недійсний або прострочений (90 с), 403 токен
іншого ключа, 409 уже використаний, 404 невідома розмова. Віджет потім прибирає токен з URL,
щоб він не витік.
Id розмови — пред’явницьке посвідчення; одноразовий короткоживучий токен — те, що не пускає його в URL, який можна поширити.