Elementy niestandardowe: API

Interfejs API to formularz, którego wypełnione wartości Skava wysyła jako JSON na adres, który wskażesz (Twój backend). Dzięki temu możesz bezpiecznie połączyć Skavę z własnymi systemami.

Konfiguracja interfejsu API

Interfejs składa się z pól wejściowych (tworzą one JSON), adresu docelowego oraz uwierzytelnienia.

1. Tworzenie pól: Każde pole otrzymuje klucz JSON. Po prawej stronie widzisz na żywo podgląd JSON, który jest wysyłany do Twojego backendu dokładnie w ten sposób.
2. Adres (URL): adres https:// Twojego backendu. Dozwolone są wyłącznie adresy HTTPS i publicznie dostępne (zobacz Bezpieczeństwo poniżej).
3. Metoda: POST (domyślnie), PUT, PATCH lub GET. W przypadku GET wartości są dodawane jako parametry zapytania zamiast wysyłania w treści.
4. Uwierzytelnianie: Ustaw nazwę nagłówka (np. Authorization) i prefiks wartości (np. Bearer ), a następnie zapisz token. Opcjonalnie ustaw datę wygaśnięcia.
5. Pola odpowiedzi (opcjonalnie): Zdefiniuj za pomocą ścieżki, które wartości z odpowiedzi backendu mają być wyświetlane: np. order.id lub items[0].sku.
6. Sprawdź za pomocą Ping i Test Request, a następnie kliknij Release.

Przechowuj token bezpiecznie

Token jest przechowywany zaszyfrowany i nigdy nie jest zwracany klientom: aplikacja pokazuje jedynie czy token jest ustawiony i kiedy wygasa. Przy wysyłaniu Skava dodaje go po stronie serwera do skonfigurowanego nagłówka. Jeśli ustawisz datę wygaśnięcia, Skava odrzuca wywołanie po upływie terminu i prosi o odnowienie tokenu.

Testowanie: Ping i Test Request

• Ping: lekka kontrola dostępności. Sprawdza wyłącznie czy Twój adres odpowiada, nie wysyłając przy tym tokena ani danych formularza. Wyświetla dostępność, status i czas odpowiedzi. Idealny jako pierwszy krok.
• Żądanie testowe: prawdziwa próba: wysyła dane przykładowe, w tym token, na Twój adres i pokazuje pełną odpowiedź oraz wyodrębnione pola odpowiedzi.

Jako administrator możesz uruchomić oba testy w trybie szkicu, aby zweryfikować integrację przed publikacją.

Szkic i publikacja

Każdy interfejs zaczyna się jako szkic i można go swobodnie edytować. Gdy wszystko jest gotowe, publikujesz go przyciskiem Publikuj.

Bezpieczeństwo

Jak zespół korzysta z opublikowanego interfejsu

Po opublikowaniu interfejsu wszyscy członkowie firmy mogą go wywołać bezpośrednio z czatu, bez konieczności korzystania z edytora. Nie ma zbiorczego wejścia ani pośredniego okna dialogowego: każdy opublikowany element znajduje się w menu plus pod własną nazwą, wraz z logo firmy, która go oferuje.

1. W czacie dotknij Plus na dole ekranu, a następnie dotknij elementu, którego chcesz użyć, na przykład Zamówienie materiałów.
2. Wypełnij formularz i naciśnij Wyślij.
3. Wynik pojawi się jako karta w czacie, widoczna dla wszystkich uczestników rozmowy.

Pozwól AI zbudować element

Jako administrator firmy nie musisz korzystać z edytora. Powiedz asystentowi Skava w czacie, np. „utwórz mi formularz zamówienia dla mojego katalogu z ilością i adresem dostawy”. Na tej podstawie tworzy szkic, później może zmieniać pola pojedynczo i zna Twój przesłany katalog artykułów: przy zamówieniach proponuje wybór produktu zamiast pola tekstowego na numer artykułu.

Może też ustawić: punkt końcowy i metodę oraz odbiorców („tylko członkowie firmy” lub „także osoby zewnętrzne w tym samym czacie”). W kwestii odbiorców najpierw pyta, zamiast od razu ustawiać, ponieważ to decyduje, kto może uruchamiać element z zewnątrz.

Czego nie dotyka: token dostępu. Nigdy o niego nie pyta i nigdy go nie przyjmuje, ponieważ wiadomości w czacie są przechowywane. Wpisujesz go samodzielnie w edytorze, inaczej żaden wywołanie nie zostanie wysłane. I nie może opublikować: ostatni krok pozostaje po Twojej stronie, więc nic nie staje się widoczne dla klientów bez sprawdzenia.

Kto może to uruchamiać

Karta „Punkt końcowy” określa, kto może korzystać z elementu. Domyślnie są to członkowie Twojej firmy. Drugie ustawienie otwiera dostęp dla osób zewnętrznych, ale tylko w czacie, w którym obecny jest ktoś z Twojej firmy: dokładnie ten przypadek, do którego to służy, czyli klient zamawiający u Ciebie. Gdy Twoja firma opuszcza czat, uprawnienie wygasa automatycznie.

Produkty z własnego katalogu

Po przesłaniu katalogu artykułów, budowa oferuje blok wybieracza produktów. Nie ma opcji do zarządzania: lista to Twój katalog. Osoba zamawiająca wyszukuje w niej, widzi obrazek, nazwę i numer artykułu, a Twój backend otrzymuje numer artykułu. Skava odrzuca numer, który nie znajduje się w Twoim katalogu. Dla ilości umieść obok zwykłe pole liczbowe.

Zdefiniuj kartę samodzielnie

Twój backend decyduje, co karta zawiera. Skava sprawdza tylko kształt, rozmiar i bezpieczeństwo, nigdy znaczenie: nie zna stanów zamówień ani nazw pól. Aby to zrobić, odpowiedz obiektem card:

{"card": {"v": 1, "title": "Order 10001", "state": "pending", "status_text": "Being picked", "fields": [{"label": "Tracking number", "value": "DPD123456789"}]}}

• v musi być liczbą całkowitą 1. Bez niej odpowiedź nie jest traktowana jako karta i zastosowane jest mapowanie odpowiedzi skonfigurowane w elemencie.
• state to tylko kolor i ikona: ok, pending, warn lub error. Wszystko, co niesie znaczenie, trafia do status_text jako swobodny tekst.
• fields to lista etykiet i wartości, maksymalnie 20 pozycji. Zbyt długie wartości są skracane, a nie odrzucane, dzięki czemu zamówienie nigdy nie zawiedzie z powodu drobnego szczegółu.

Dane wprowadzone przez użytkownika należą do serwera: pozostają nietknięte niezależnie od tego, co wysyła Twoje zaplecze. Stanowią one zapis w czacie tego, co faktycznie zostało przesłane.

Zgłaszanie statusu później

Podczas uruchomienia elementu Skava wysyła dwie dodatkowe wartości: callback_url i callback_token. Później zgłoś tam nowy stan, a w czacie pojawi się nowa karta, również na telefonie, gdy ktoś na nią patrzy. Poprzednia karta pozostaje, co pozwala odczytać, jaki stan został zgłoszony. Wyślij ten sam obiekt card jak powyżej, metodą POST z nagłówkiem Authorization: Bearer <callback_token>. Trzy opcjonalne wartości umieszczaj obok karty:

• seq: własny licznik. Raport o mniejszej lub równej wartości jest odrzucany, dzięki czemu dwa raporty nie mogą się wyprzedzić.
• final: zamyka interakcję. Token staje się nieważny, a karta jest ostateczna.
• notify: ustaw na false, aby opublikować kartę cicho, bez licznika nieprzeczytanych i bez powiadomienia. Do kroków pośrednich, które nie powinny nikogo budzić. Bez tego parametru karta jest zwykłą wiadomością.

Interakcja może opublikować maksymalnie 50 kart. Ten sam raport wysłany dwukrotnie nie generuje drugiej karty.

Skava odpowiada kodem 200 i listą hints, jeśli cokolwiek zostało skrócone lub usunięte, oraz kodem 422, jeśli karta była nieprzydatna. Interakcja przyjmuje raporty przez 90 dni.

Karty są wysyłane przez systemowy nadawcę Skavy, a nie przez osobę, która uruchomiła element, ani przez konto Twojej firmy. Informacja o tym, który system jest nadawcą, znajduje się w tytule karty.

Kompletny przykład do skopiowania znajduje się w repozytorium w katalogu example_order_server/ i działa na api.skava.io.

Powiązane

Chcesz raczej stworzyć szablon dokumentu do wypełnienia? Zobacz Custom Elements: Dokumenty.

Najczęściej zadawane pytania