Інструменти та події в панелі: ваш власний API

Інструмент дає помічнику змогу поставити питання вашій власній системі, поки він відповідає, — вашому каталогу, вашій сітці тарифів, статусу замовлення — і відповісти з того, що повернеться. Подія дає йому змогу показати результат у власному інтерфейсі вашої сторінки: сітку товарів, вікно тарифів, модальне вікно. І те, і те налаштовується на екрані сайту Інструменти, і обидва входять у тариф Growth і вищі.

Сам ендпоінт — частина роботи вашого розробника. Що він має повертати і як зібрано сітку тарифів і магазин на цьому сайті — у покроковому прикладі для розробників.

Екран

Інструменти та події має два списки: Кастомні інструменти і Кастомні події, кожен зі своєю кнопкою Новий інструмент чи Нова подія. Рядок показує назву; інструмент, що надсилає подію, має позначку емітує подію, а подія, яку він надсилає, — авто-емісія. Клік по рядку відкриває його форму; у меню рядка є Редагувати, Увімкнути чи Вимкнути і Видалити; а кнопка Тест (в інструмента) чи Симуляція (у події) відкриває панель поруч зі списками, де ви пробуєте його, не залишаючи екран.

Інструмент

Форма йде в тому порядку, в якому ви її заповнюєте. Зберегти вгорі зберігає її.

Основне

• Назва для показу — те, що бачите ви в панелі.
• Ім’я — те, що бачить помічник: літери, цифри, - і _, унікальне на сайті (plan_grid, order_status).
• Увімкнено — вимкнений інструмент зберігається, але не використовується.
• Область агентів — один агент сайту або Усі агенти.
• Коли використовувати — ситуації, у яких помічник має його викликати, простими словами. Саме це він читає, вирішуючи, тож пишіть так, як питає відвідувач: «будь-яке питання про тарифи, ціни чи який тариф підходить; ніколи не називати ціни з пам’яті».

Запит

• Метод — GET, щоб читати, POST, щоб надсилати.
• URL — https-адреса вашого ендпоінта.
• Заголовки і Query-параметри — сталі значення, що йдуть із кожним викликом, наприклад Authorization: Bearer {{secret.api_token}}.
• Шаблон тіла (JSON) — для POST тіло, яке треба надіслати.
• Тайм-аут — у мілісекундах, 5000, якщо не змінити, щонайбільше 10 секунд.

Параметри — те, що помічник заповнює з розмови. Кожен має Ім’я, Тип (string, number, integer, boolean, array), Обов’язк., Розташ. (query, body, path, header) і Опис — один рядок, що каже помічнику, що туди писати. Пошуковий запит позначайте обов’язковим, щоб кожен виклик був пошуком; фільтри лишайте необов’язковими, щоб помічник брав лише ті, що дає питання відвідувача.

Секрети — токени вашого API, збережені зашифрованими. Спершу збережіть інструмент, тоді вкажіть Ім’я і Значення й натисніть Додати; Копіювати плейсхолдер дає {{secret.name}}, щоб вставити в заголовок. Секрет зберігається тієї ж миті, коли ви його додаєте, і його значення більше ніколи не показується.

Відповідь

• Що означає відповідь — кожне поле, яке повертає ваш ендпоінт, по реченню на поле, з одиницею: «price_usd — долари США на місяць». Помічник читає це раніше за дані.
• Шлях у відповіді — де в відповіді лежить список, через крапки (plans, data.items). Тоді помічник бачить лише цю частину.
• У Додатково: Кешувати відповіді (рідко змінні дані) — для живих даних лишайте вимкненим — і Мова: якщо ваш ендпоінт приймає мову, перелічіть Мови, які підтримує API і вкажіть Параметр мови: тоді кожен виклик несе мову відвідувача, коли ваш API нею говорить, і основну мову сайту, коли ні.

Доступність — Усі екрани або Лише вказані екрани з полем Екрани, де він доступний. Інструмент на всіх екранах пропонується з кожним повідомленням; тримайте таких мало, а решту прив’язуйте до сторінок, де вони мають сенс.

Емітує подію — оберіть подію, і щоразу, коли інструмент щось повертає, ця подія надсилається на вашу сторінку з усім результатом. Сам помічник цю подію більше не надсилає.

Подія

Основне — Назва для показу, Ім’я (його слухає ваша сторінка), Увімкнено, Область агентів і Коли емітувати.

Поля payload — що несе подія. Для списку результатів — одне поле типу array.

Поведінка

• Не пропонувати перехід на сторінку — результат показує сама ваша сторінка, тож помічник не пропонує ще й кудись перейти.
• Відповідати коротко замість повної відповіді — помічник каже, що знайшов відповідь, а показує її ваша сторінка. Для сітки товарів — так. Для «який тариф найдешевший?», де відвідувач чекає речення, — ні.
• Спочатку питати згоди — помічник питає, перш ніж подія спрацює, і надсилає її на «так» відвідувача.

Доступність — як в інструмента. Звʼязок перелічує інструменти, що надсилають цю подію.

Тест і Симуляція

Тест запускає збережений інструмент насправді: заповніть Приклади параметрів і натисніть Запустити, щоб побачити відповідь вашого ендпоінта, а з Емітує подію — що Емітувала б подію. Тест завжди викликає ваш ендпоінт, тож показує те, що ваша система відповідає просто зараз.

Симуляція надсилає подію з Прикладами значень і показує Дію, яку отримує хост, та фрагмент Слухач на хості, щоб скопіювати його для розробника.

Ваш тариф

Інструменти й події працюють на Growth, Pro і Business. На іншому тарифі екран каже, що ваш тариф їх не включає, Новий інструмент і Нова подія чекають тарифу, який їх має, а вже створені інструменти зберігаються з позначкою Не у вашому плані — готові на той час, коли ви зміните тариф.

Інструменти на інших екранах

Ті самі інструменти обираються і в інших місцях панелі:

• Агент → Ескалація → Надсилати звернення у вашу систему — POST-інструмент, що отримує кожен контакт, який лишає відвідувач. Агент.
• Для застосунків джерела → Інструменти на цьому екрані і Проактивний аналіз — інструменти, прив’язані до екрана вашого застосунку, і перевірка, яку помічник запускає там сам. Джерела.