Skava Skava / Wiki

Підключення власних елементів для розробників

Ця сторінка призначена для розробників, які підключають бекенд компанії до Skava. Створення та публікація API-елемента описано на сторінці Власні елементи: інтерфейси API; тут ми розглядаємо все, що має відбуватися на іншому кінці з’єднання.

Ідея в одному реченні: Skava не знає вашої предметної галузі. Вона знає лише один формат, а саме картку. Ви вирішуєте, що на ній буде написано, а ми перевіряємо лише структуру, розмір та безпеку. Замовлення матеріалів є одним із прикладів; наступна компанія збирає зворотний зв’язок від користувачів, а ще одна зберігає фото об’єкта у власних записах.

Огляд процесу

  1. Адміністратор компанії створює API-елемент у Skava: форму, а також адресу, метод і токен вашого бекенда.
  2. Хтось у чаті заповнює форму та надсилає її.
  3. Skava викликає ваш бекенд і надсилає заповнені значення у форматі JSON.
  4. Ваша відповідь перетворюється на картку у чаті.
  5. За бажанням ви можете пізніше повідомляти про нові стани через callback. Кожне повідомлення стає окремою карткою, а попередня залишається.

Вимоги до вашого бекенду

  • HTTPS. Тільки https://, без http, без облікових даних у адресі, максимум 2000 символів.
  • Доступність ззовні. Хост має розв'язуватися виключно в публічні IP-адреси. Локальний хост, приватні мережі, link-local та метадані хмари відхиляються, і це перевіряється при кожному виклику.
  • Фіксована адреса. Skava розв'язує хост один раз і прив'язує з'єднання до цієї IP-адреси. Зміна DNS під час виклику не має значення.
  • Без редиректів. Перехід 301 на «правильну» адресу вважається помилкою. Введіть кінцеву адресу одразу.
  • Час відповіді. Тайм-аут налаштовується для кожного елемента і обмежений 30 секундами. Якщо потрібно більше, відповідайте одразу та надсилайте результат пізніше через callback.
  • Розмір відповіді. Skava читає не більше 256 КіБ.
  • Content-Type. Тіло обробляється лише за application/json.

Запит, який доходить до вас

Метод є GET, POST, PUT або PATCH, залежно від елемента. При POST, PUT та PATCH значення надходять як JSON-тіло, при GET як параметри запиту.

Автентифікація виконується за допомогою одного заголовка, назва якого та префікс значення налаштовуються в елементі, зазвичай Authorization з префіксом Bearer . Токен зберігається зашифрованим на нашому боці. Заголовки host, content-length, content-type, cookie та accept-encoding не можна встановити.

Тіло є плоским об'єктом. Ключі обирає той, хто створював елемент; вкладеність з'являється лише там, де додано таблицю або вибір продукту:

{"artikelnummer": "5100110", "menge": 20, "note": "Please deliver in the morning", "orderer": "Jonas Berger", "company": "Sanitar Berger GmbH", "project": "Spitalstrasse 11", "locale": "de", "callback_url": "https://chat.skava.io/api/v1/custom-elements/interactions/…", "callback_token": "…"}

Три ключі завжди надходять від нас, тому не використовуйте їх самостійно:

  • locale: код мови користувача. Відповідайте цією мовою; ми не перекладаємо ваші тексти.
  • callback_url та callback_token: зворотний виклик для цієї конкретної взаємодії, див. нижче. Вони присутні лише тоді, коли виклик іде з чату.

Поля контексту, такі як ім'я, компанія, проєкт або підчат, заповнюються самим сервером на основі каналу, де запускався елемент. Зламаний клієнт не може вказати там іншу назву проєкту.

Відповідь: формат картки

Відповідайте кодом 2xx та об'єктом card. Саме так у чаті з'являється картка:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Order received", "icon": "package", "fields": [{"label": "Order number", "value": "BST-10001"}, {"label": "Expected", "value": "14/08/2026"}]}}

  • v (обов'язково): ціле число 1. У текстовому вигляді ("1") відповідь відхиляється. Якщо цього поля немає, відповідь не вважається карткою, і застосовується мапування відповіді, налаштоване в елементі.
  • title: заголовок картки.
  • state: лише колір і відтінок іконки, одне зі значень ok, pending, warn, error. Невідоме значення замінюється на ok, і ви отримуєте підказку.
  • status_text: вільний текст, який ми не інтерпретуємо. Він розташований у верхній частині картки та відображається у списку чатів і в push-сповіщенні.
  • fields: список label та value. Максимум 20 записів, label до 80 символів, value до 200, title та status_text по 120 символів кожен. Занадто довгі значення скорочуються, а не відхиляються: замовлення не повинне провалитися через дрібницю.
  • icon: див. нижче.

Що Skava робить із вашими текстами перед тим, як вони потрапляють у чат: символи перенесення рядка та керуючі символи видаляються (інакше символ, що читається справа наліво, міг би перевернути відображення суми), зворотні лапки замінюються, а все, що починається з [SKAVA:, нейтралізується. Останнє запобігає тому, щоб значення картки було прочитане як інший елемент чату, наприклад як запит на оплату.

Посилання у полях, HTML та зображення не можна встановити. Чат є середовищем довіри, а клікабельна адреса з чужого бекенду стала б запрошенням перебудувати сторінку входу.

Введення користувача належать серверу: вони з'являються на першій картці, і ви не можете їх перезаписати. У чаті вони є записом того, що було фактично надіслано.

Іконки

За допомогою icon картка отримує власний знак у заголовку. Два способи:

Назва з вбудованого набору: package, package-check, package-open, box, boxes, truck, forklift, warehouse, settings, cog, gauge, wrench, hammer, drill, hard-hat, ruler, paint-roller, construction, clipboard-check, receipt, file-text, camera, clock, calendar-clock, circle-check, circle-alert, triangle-alert, send, mail-check, shopping-cart, credit-card, map-pin.

Або власний SVG у вигляді рядка. З нього Skava бере лише геометрію (path, circle, ellipse, rect, line, polyline, polygon з їхніми числовими атрибутами) і будує власне зображення. Скрипти, стилі, зовнішні посилання, foreignObject та атрибути подій відкидаються; наявність doctype або сутності призводить до відхилення; файл може бути не більше 8 КіБ і містити не більше 16 фігур. Колір, товщину лінії та розмір встановлює Skava, тому іконка не може замаскуватися під елемент керування. Працюйте на сітці 24 на 24.

Без icon залишається позначка за замовчуванням.

Зворотний виклик: повідомлення про подальші стани

У виклику містяться callback_url та callback_token. Використовуйте їх, щоб пізніше повідомляти про нові стани:

POST <callback_url> з заголовками Authorization: Bearer <callback_token> та Content-Type: application/json, тіло запитом не більше 32 КіБ:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Shipped", "icon": "truck", "fields": [{"label": "Tracking number", "value": "DPD123456789"}]}, "seq": 3, "final": false}

Окрім картки, є три необов'язкові значення:

  • seq: ваш власний лічильник. Звіт із меншим або рівним значенням відкидається, щоб два звіти не могли обійти один одного. Без seq перемагає той, що прийшов останнім.
  • final: закриває взаємодію. Токен стає недійсним, і більше картки не з'являються. Також дозволено у першій відповіді, для сценаріїв без подальших кроків.
  • notify: встановіть false, щоб опублікувати картку тихо, без лічильника непрочитаних і без сповіщення. Для проміжних кроків, які не повинні будити нікого. Без цього параметра картка є звичайним повідомленням.

Кожен звіт стає окремою карткою в чаті, попередня залишається. Так зрозуміло, який стан було доповідено. Звідси випливає рекомендація: надсилайте лише те, що змінилося. Картка, яка в четвертий раз повторює номер замовлення, позиції та суму, є просто шумом для читача.

Два обмеження: однаковий звіт двічі не створює другу картку, а взаємодія може опублікувати максимум 50 карток. Взаємодія приймає звіти протягом 90 днів.

Відповіді, на які слід реагувати

  • 200 з {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Прочитайте підказки: вони вказують, що було скорочено або видалено.
  • 401: неправильний токен або ідентифікатор взаємодії. Не повторюйте спробу.
  • 410: взаємодію закрито або вона прострочена. Не повторюйте спробу.
  • 422: картка непридатна до використання, причиною є hints. Спочатку виправте це.
  • 400 пошкоджений JSON, 413 занадто великий обсяг, 429 занадто багато запитів (повторіть із затримкою), 500 помилка на нашому боці, повторіть пізніше.

Приклад 1: замовлення з історією статусів

Крок 1, запит до вашого бекенду:

POST https://api.example.com/v1/orders
Authorization: Bearer <your token>
{"artikelnummer": "5100110", "menge": 20, "orderer": "Jonas Berger", "company": "Sanitar Berger GmbH", "locale": "de", "callback_url": "https://chat.skava.io/api/v1/custom-elements/interactions/1111…", "callback_token": "secret"}

Крок 2, ваш миттєвий відгук:

{"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Order received", "icon": "package", "fields": [{"label": "Order number", "value": "BST-10001"}, {"label": "Expected", "value": "14/08/2026"}]}}

У чаті тепер відображається картка з іконкою посилання, статусом та введеними даними користувача.

Крок 3, пізніше під час вибору:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Being picked", "icon": "cog", "fields": []}, "seq": 2, "notify": false}

Тиха друга картка без полів: змінився лише статус.

Крок 4, при відправці:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "pending", "status_text": "Shipped", "icon": "truck", "fields": [{"label": "Tracking number", "value": "DPD123456789"}, {"label": "Carrier", "value": "DPD"}]}, "seq": 3}

Ця картка може розбудити когось, тому notify: false не вказано.

Крок 5, при доставці:

POST <callback_url> to {"card": {"v": 1, "title": "Order BST-10001", "state": "ok", "status_text": "Delivered", "icon": "package-check", "fields": []}, "seq": 4, "final": true}

Завдяки final взаємодія закривається, а токен більше не діє.

Приклад 2: дія без подальших кроків

Не в кожному процесі є історія. Елементу з одним полем, який передає дані у вашу систему, потрібна лише одна відповідь:

{"card": {"v": 1, "title": "Filed", "state": "ok", "status_text": "Stored under project 4711", "icon": "clipboard-check", "fields": [{"label": "Case", "value": "4711"}]}, "final": true}

Тут важливе значення final: true: інакше взаємодія залишалася б відкритою на 90 днів із діючим токеном, хоча ви більше нічого не звітите.

Вибір продукту з каталогу

Після того, як компанія завантажить свій каталог статей, елемент може містити блок вибору товару. Користувач формує з нього кошик, а ви отримуєте його як список під ключем, який обрав автор елемента:

{"items": [{"artikelnummer": "5100110", "menge": 20}, {"artikelnummer": "5100111", "menge": 2}], "note": "…"}

Оскільки ключ довільний, шукайте перший список із такою структурою, а не конкретну назву. Перед відправкою Skava перевіряє, чи існують усі позиції в каталозі цієї компанії, максимум 50 позицій. У картці позиції відображаються списком із зображенням товару, назвою та кількістю.

Тестування

  • Кнопка Ping у редакторі елементів надсилає простий запит HEAD без токена та даних. Відповідайте будь-яким HTTP-відповіддю, щоб система визнала сервіс доступним.
  • Кнопка Test request виконує реальний виклик із тестовими значеннями, навіть якщо елемент ще в статусі чернетки, і показує запит, відповідь та повідомлення валідатора картки.
  • Попередній перегляд у сусідній вкладці: вставте ваш JSON-відповідь, перевірте, і ви побачите готову картку разом із підказками. Перевірка виконується на сервері тим самим кодом, що й у продакшені.
  • Приклад сервера: повний приклад постачальника працює на api.skava.io і використовує все описане вище. Його код знаходиться в репозиторії у папці example_order_server/, це близько 600 рядків чистого стандартного бібліотечного коду, призначеного для копіювання.

Ще кілька важливих моментів

  • Картка є звичайним повідомленням у чаті. Вона з'являється в пошуку, може бути цитованою та залишається в історії.
  • Вона надсилається системним відправником, а не акаунтом вашої компанії. Вона все одно з'являється на боці того, хто запустив елемент, а в заголовку вказано, чия система це пише.
  • Хто може ним користуватися, визначається на самому елементі: лише члени компанії або також зовнішні учасники, які мають спільний чат. Коли ваша компанія виходить із чату, дозвіл автоматично припиняє дію.
  • API-елемент із простроченим токеном перебуває в стані сну: поточні додатки приховують його в меню, а виклик, надісланий попри це, відхиляється на сервері. Адміністратор зберігає для нього новий токен, що працює навіть на опублікованому інтерфейсі.

Пов'язані матеріали

Створення та публікація: Кастомні елементи: API-інтерфейси. Заповнювані документи замість інтерфейсів: Кастомні елементи: Документи.