Огляд API: рантайм і API керування
Для розробників, у коді: два API — рантайм, з яким говорить віджет, і API керування, з яким говорить панель, — для чого кожен, як автентифікується і всі ліміти в одній таблиці.
Два API
| Рантайм | API керування | |
|---|---|---|
| база | data-agent-base з вашого фрагмента |
хост вашої панелі, /api/ |
| говорить із | віджетом (і власним фронтендом) | панеллю (і вашими скриптами) |
| автентифікація | ключ віджета сайту — публічний за задумом, обмежений вказаними для нього origin | ключ керування — секретний, показується раз, обмежений власником |
| що робить | розмову (WS /ws, POST /message), конфігурацію віджета, мовлення і розпізнавання, два маячки |
усе, що робить панель: сайти, джерела, помічники, віджети, інструменти, події, ключі, розмови, аналітика, оплата |
| довідник | сторінки цього розділу | генерується з /api/schema/ — Swagger на /api/docs/, ReDoc на /api/redoc/ |
Runtime API потрібен лише щоб зробити власний фронтенд; віджет уже ним говорить. API керування потрібен, щоб автоматизувати панель — створювати джерела з вашої CMS, читати розмови у своє сховище, змінювати ключ.
Фактично публічний
Оскільки ключ віджета публічний, кожен ендпоінт рантайму, який він автентифікує, доступний
будь-кому на дозволеному origin — і небраузерному клієнту, що підробляє заголовок Origin.
Рантайм для цього й збудований: ніщо з того, що він віддає, не більше за те, що бачив би
відвідувач; кожен запис обмежений частотою й межами (перехід може лише збільшити наявну
пропозицію; передача лише реєструє заявку), а маячки відповідають 204 на кожну невдачу, тож
нічого не розкривають. Id розмови — це пред’явницьке посвідчення: хто його має, той може
продовжити чат, — тому він ніколи не кладеться в URL, який можна поширити.
Тому ліміти, що мають значення, рахуються там, де скрипт їх не змінить: на відвідувача (одна адреса на одному сайті), щоб один клієнт не забрав увесь ліміт, і на власника, щоб акаунт без тарифу міг лише спробувати асистента. Вимкнений у панелі віджет зупиняє сам чат, а не лише кнопку: хід, що називає вимкнений віджет, або будь-який хід на сайті, де всі віджети вимкнені, отримує 403. Відкликаний ключ віджета зупиняє все одразу.
Справжній секрет — ключ керування. Тримайте його на сервері.
Усі ліміти в одній таблиці
| Ліміт | Значення | Стосується |
|---|---|---|
| чат, на акаунт за хвилину | 30 · 60 · 180 · 360 · 900 (до тарифу · Starter · Growth · Pro · Business) | /message, повідомлень /ws |
| чат, на відвідувача | 20 / хв, 300 / добу (відвідувач — одна адреса на одному сайті) | /message, повідомлень /ws |
| до тарифу | 50 кредитів на добу, 300 на місяць; 20 000 символів мовлення і 100 потоків розпізнавання на добу | кожен запит ключа власника |
| кредитів на місяць | 3 000 · 7 000 · 18 000 · 52 000 за тарифом, плюс докуплені | кожен хід із відповіддю |
| мовлення | 120 / хв; 1 200 символів на запит; 60 / хв і 30 000 символів на добу на відвідувача; на акаунт — 20 000 на добу плюс 2 500 за кожну відповідь | POST /tts |
| розпізнавання | 60 потоків / хв; 120 с на потік; 20 / хв і 300 / добу на відвідувача; на акаунт — 200 на добу плюс 6 за кожну відповідь | WS /ws/stt |
| передача | 30 / хв | POST /handoff, /handoff/opened |
| маячок переходу | 120 / хв | POST /followed |
| голосові таймінги | 120 / хв | кадр voice_timing |
| перевірка інструмента | 30 / хв на власника | «Перевірити» в панелі |
| власний інструмент | 3 виклики за хід; стеля 10 с; 256 KB; стеля кешу 600 с; 8 одночасних | кожен виклик інструмента |
| прив’язаних інструментів і подій | 12 інструментів і 12 подій за хід серед прив’язаних до екрана, за назвою; решта відкидається лише з записом у журналі сервера | кожен хід |
| дії на сторінці | 40 обмінів за хід; 40 кроків на виклик; 5 с на обмін; 1,5 с попереднє зчитування | ходи з діями на сторінці |
| токен передачі розмови | 90 с, одноразовий | GET /conversation |
| кеш конфігурації віджета | 1 год | GET /widget/config |
| аналіз при онбордингу | 20 / хв на власника | POST /api/onboarding/analyze/ |
Кожен ліміт сплеску — фіксоване вікно за хвилину, на акаунт і, де таблиця так каже, на кожного
відвідувача. Понад нього: HTTP 429 або кадр error з code: "rate_limited" на сокеті, і кредит
не витрачається. На місячній стелі хід отримує повідомлення про ліміт, віджет стає неактивним з
наступного завантаження, а власник отримує лист; до тарифу обсяг закінчується так само, без листа.
Версії і стабільність
У кожного API одна версія. Протокол кадрів адитивний — новий серверний кадр для старішого віджета лише дорадчий, — а зникнення ключа з відповіді оголошується в журналі змін. Бандл віджета віддається з CDN і оновлюється на місці; сторінка ніколи не закріплює версію бандла.