Ta strona jest przeznaczona dla programistów łączących backend firmy ze Skava. Tworzenie i publikowanie elementu API omówiono na stronie Custom Elements: interfejsy API; tutaj opisujemy wszystko, co musi się wydarzyć po drugiej stronie połączenia.

Główna idea w jednym zdaniu: Skava nie zna Twojej dziedziny. Zna dokładnie jeden format, czyli kartę. Ty decydujesz, co na niej się znajduje, my sprawdzamy tylko kształt, rozmiar i bezpieczeństwo. Przykładem może być zamówienie materiałów; jedna firma zbiera opinie użytkowników, kolejna archiwizuje zdjęcia placu budowy we własnych rejestrach.

Przegląd przepływu

1. Administrator firmy tworzy w Skava element API: formularz oraz adres, metodę i token swojego backendu.
2. Ktoś w czacie wypełnia formularz i go wysyła.
3. Skava wywołuje Twoje backend i przesyła wypełnione wartości jako JSON.
4. Twoja odpowiedź staje się kartą w czacie.
5. Opcjonalnie możesz później zgłaszać nowe stany przez callback. Każda zgłoszona informacja tworzy nową kartę; poprzednia pozostaje.

Wymagania dla Twojego backendu

• HTTPS. Tylko https://, bez http, bez danych uwierzytelniających w adresie, maksymalnie 2000 znaków.
• Dostęp publiczny. Host musi rozwiązywać się wyłącznie na publiczne adresy IP. Adresy localhost, sieci prywatne, link-local oraz metadane chmury są odrzucane i sprawdzane przy każdym wywołaniu.
• Stały adres. Skava rozwiązuje host raz i przypisuje połączenie do tego adresu IP. Zmiana DNS w trakcie wywołania nie ma żadnego efektu.
• Brak przekierowań. Przekierowanie 301 do „poprawnego” adresu jest traktowane jako niepowodzenie. Wprowadź od razu ostateczny adres.
• Czas odpowiedzi. Limit czasu jest konfigurowalny dla każdego elementu i sztywno ograniczony do 30 sekund. Jeśli potrzebujesz więcej czasu, odpowiedz natychmiast i zgłoś wynik później przez wywołanie zwrotne.
• Rozmiar odpowiedzi. Skava odczytuje maksymalnie 256 KiB.
• Content-Type. Treść jest parsowana wyłącznie jako application/json.

Żądanie, które dociera do Ciebie

Metoda to GET, POST, PUT lub PATCH, w zależności od elementu. Przy POST, PUT i PATCH wartości przybywają jako ciało JSON, przy GET jako parametry zapytania.

Uwierzytelnianie to jeden nagłówek, którego nazwa i prefiks wartości są skonfigurowane w elemencie, zazwyczaj Authorization z prefiksem Bearer . Token jest przechowywany zaszyfrowany po naszej stronie. Nie można ustawić nagłówków host, content-length, content-type, cookie oraz accept-encoding.

Ciało to płaski obiekt. Klucze są wybierane przez twórcę elementu; zagnieżdżenie pojawia się tylko tam, gdzie dodano tabelę lub wybór produktu:

{"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": "…"}

Trzy klucze zawsze pochodzą od nas, więc nie używaj ich samodzielnie:

• locale: kod języka użytkownika. Odpowiadaj w tym języku; nie tłumaczymy Twoich tekstów.
• callback_url i callback_token: wywołanie zwrotne dla tej jednej interakcji, zobacz poniżej. Są obecne tylko wtedy, gdy wywołanie pochodzi z czatu.

Pola kontekstowe, takie jak nazwa, firma, projekt lub podczat, są wypełniane przez sam serwer na podstawie kanału, w którym uruchomiono element. Zmanipulowany klient nie może tam podać innej nazwy projektu.

Odpowiedź: format karty

Odpowiedz kodem 2xx i obiektem card. To dokładnie to, co staje się kartą w czacie:

{"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 (wymagane): liczba całkowita 1. Jako tekst ("1") zostanie odrzucona. Bez niej odpowiedź nie jest traktowana jako karta i zastosowane zostanie mapowanie odpowiedzi skonfigurowane w elemencie.
• title: nagłówek karty.
• state: tylko kolor i odcień ikony, jedna z wartości: ok, pending, warn, error. Nieznana wartość zostanie zastąpiona wartością ok i otrzymasz wskazówkę.
• status_text: dowolny tekst, którego nie interpretujemy. Znajduje się na górze karty i to właśnie on pojawia się w liście czatów oraz w powiadomieniu push.
• pola: lista etykiety i wartości. Maksymalnie 20 wpisów, etykieta do 80 znaków, wartość do 200, tytuł i status_text po 120 każdy. Zbyt długie wartości są skracane, a nie odrzucane: zamówienie nie powinno się niepowodować z powodu szczegółu.
• ikona: zobacz poniżej.

Co Skava robi z Twoimi tekstami przed wysłaniem do czatu: usuwa znaki nowej linii i znaki sterujące (znak od prawej do lewej mógłby inaczej wyświetlić kwotę), zastępuje znaki tyldy i dezaktywuje wszystko, co zaczyna się od [SKAVA:. Ostatnie zapobiega interpretacji wartości karty jako innego elementu czatu, na przykład żądania płatności.

Linki w polach, HTML i obrazach nie mogą być ustawiane. Czat to zaufane środowisko, a klikalny adres z obcego backendu byłby zaproszeniem do odtworzenia strony logowania.

wprowadzone dane użytkownika należą do serwera: pojawiają się na pierwszej karcie i nie można ich nadpisać. W czacie stanowią zapis tego, co faktycznie zostało przesłane.

Ikony

Atrybut icon dodaje własny znak w nagłówku karty. Dostępne są dwie opcje:

Nazwa z zestawu wbudowanego: 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.

Lub własny plik SVG jako ciąg znaków. Skava pobiera z niego wyłącznie geometrię (path, circle, ellipse, rect, line, polyline, polygon wraz z ich atrybutami numerycznymi) i tworzy własny obraz. Skrypty, style, odwołania zewnętrzne, foreignObject oraz atrybuty zdarzeń są odrzucane; deklaracja typu dokumentu lub encja powoduje odrzucenie pliku; plik może mieć maksymalnie 8 KiB i zawierać co najwyżej 16 kształtów. Kolor, grubość obrysu i rozmiar są ustawiane przez Skava, więc ikona nie może udawać elementu sterowania. Pracuj na siatce 24 na 24.

Bez atrybutu icon pozostaje domyślny znak.

Callback: zgłaszanie późniejszych stanów

Wywołanie zawiera callback_url oraz callback_token. Użyj ich do późniejszego zgłaszania nowych stanów:

POST <callback_url> z nagłówkami Authorization: Bearer <callback_token> oraz Content-Type: application/json, ciało żądania do 32 KiB:

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

Oprócz karty dostępne są trzy opcjonalne wartości:

• seq: Twój własny licznik. Raport z mniejszą lub równą wartością jest odrzucany, dzięki czemu dwa raporty nie mogą się wyprzedzić. Bez seq wygrywa ten, który dotrze jako ostatni.
• final: kończy interakcję. Token traci ważność i nie pojawiają się kolejne karty. Dozwolone również w first odpowiedzi, dla przepływów bez dalszych kroków.
• notify: ustaw na false, aby opublikować kartę cicho, bez licznika nieprzeczytanych i bez powiadomienia. Przeznaczone dla kroków pośrednich, które nie powinny budzić nikogo. Bez tego ustawienia karta jest zwykłą wiadomością.

Każda raportowana zmiana tworzy własną kartę w czacie, poprzednia pozostaje. Dzięki temu wiadomo, jaki stan został zgłoszony. Stąd rekomendacja: wysyłaj tylko to, co się zmieniło. Karta powtarzająca numer zamówienia, pozycje i sumę po raz czwarty to tylko szum dla odbiorcy.

Dwa limity: ten sam raport wysłany dwukrotnie nie generuje drugiej karty, a interakcja może opublikować maksymalnie 50 kart. Interakcja akceptuje raporty przez 90 dni.

Odpowiedzi, na które należy zareagować

• 200 z {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Przeczytaj wskazówki: mówią, co zostało skrócone lub pominięte.
• 401: nieprawidłowy token lub identyfikator interakcji. Nie powtarzaj próby.
• 410: interakcja zamknięta lub wygasła. Nie powtarzaj próby.
• 422: karta nie do użycia, z wskazówkami jako przyczyną. Najpierw to napraw.
• 400 uszkodzony JSON, 413 za duże, 429 zbyt wiele żądań (powtórz z opóźnieniem), 500 nasza wina, spróbuj później.

Przykład 1: zamówienie z historią statusów

Krok 1, żądanie do Twojego backendu:

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"}

Krok 2, Twoja natychmiastowa odpowiedź:

{"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"}]}}

Czat wyświetla teraz kartę z ikoną paczki, statusem oraz danymi wprowadzonymi przez użytkownika.

Krok 3, później podczas kompletacji:

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

Cicha druga karta bez pól: zmienił się tylko status.

Krok 4, przy wysyłce:

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}

Ta karta może kogoś obudzić, więc nie ma notify: false.

Krok 5, przy dostawie:

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

Z final interakcja jest zamknięta i token już nie działa.

Przykład 2: akcja bez dalszych kroków

Nie każdy przepływ ma historię. Element z jednym polem, który przekazuje coś do Twojego systemu, wymaga tylko jednej odpowiedzi:

{"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 ma tu znaczenie: w przeciwnym razie interakcja pozostanie otwarta przez 90 dni z ważnym tokenem, mimo że nigdy więcej nic nie zgłosisz.

Wybór produktu z katalogu

Gdy firma wgra swój katalog artykułów, element może zawierać blok wybierania produktów. Użytkownik tworzy z niego koszyk, a Ty otrzymujesz go jako listę pod kluczem wybranym przez twórcę elementu:

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

Ponieważ klucz jest dowolny, wyszukaj pierwszą listę o takim kształcie, a nie o ustalonej nazwie. Przed wysłaniem Skava sprawdza, czy każda liczba rzeczywiście istnieje w katalogu tej firmy, maksymalnie 50 pozycji. W karcie pozycje pojawiają się jako lista z obrazkiem produktu, nazwą i ilością.

Testowanie

• Ping w edytorze elementu wysyła czysty HEAD bez tokena i bez danych. Odpowiedz czymkolwiek; każda odpowiedź HTTP oznacza osiągalność.
• Testowe żądanie wykonuje prawdziwe wywołanie z przykładowymi wartościami, nawet gdy element jest nadal w wersji roboczej, i pokazuje żądanie, odpowiedź oraz komunikaty walidatora karty.
• Podgląd na sąsiedniej karcie: wklej swój JSON odpowiedzi, sprawdź i zobacz gotową kartę wraz z podpowiedziami. Jest sprawdzana na serwerze tym samym kodem co w produkcji.
• Przykładowy serwer: kompletny przykład dostawcy działa na api.skava.io i wykorzystuje wszystko opisane powyżej. Jego kod źródłowy znajduje się w repozytorium w katalogu example_order_server/, liczy około 600 linii czystej biblioteki standardowej i jest gotowy do skopiowania.

Co jeszcze warto wiedzieć

• Karta to zupełnie zwyczajna wiadomość czatu. Pojawia się w wynikach wyszukiwania, można ją cytować i pozostaje w historii.
• Wysyła ją nadawca systemowy, nie konto Twojej firmy. Wiadomość pojawia się jednak po stronie osoby, która uruchomiła element, a w nagłówku podany jest system, który ją wysłał.
• Na elemencie ustawia się, kto może go uruchomić: tylko członkowie firmy lub również osoby z zewnątrz, które współdzielą czat. Gdy Twoja firma opuści czat, uprawnienia wygasają automatycznie.
• Element API z wygasłym tokenem jest nieaktywny i nie pojawia się nawet w menu, dopóki administrator nie zapisze nowego.

Powiązane

Tworzenie i publikowanie: Custom Elements: interfejsy API. Dokumenty do wypełnienia zamiast interfejsów: Custom Elements: dokumenty.