Připojení vlastních prvků pro vývojáře

Tato stránka je určena vývojářům, kteří propojují backend společnosti se Skavou. Vytvoření a vydání API prvku je popsáno na stránce Vlastní prvky: rozhraní API; zde se věnujeme všemu, co se musí odehrát na druhé lince.

Myšlenka v jedné větě: Skava nezná vaši doménu. Zná přesně jeden formát, a to kartu. Vy určujete, co na ní stojí, my kontrolujeme pouze tvar, velikost a bezpečnost. Objednávka materiálu je jeden příklad; další společnost sbírá zpětnou vazbu uživatelů, ta další ukládá fotku stavu do svých záznamů.

Přehled toku

1. Administrátor společnosti vytvoří v Skavě API prvek: formulář a adresu vašeho backendu, metodu a token.
2. Někdo v chatu vyplní formulář a odešle ho.
3. Skava zavolá váš backend a odešle vyplněné hodnoty jako JSON.
4. Vaše odpověď se stane kartou v chatu.
5. Volitelně můžete později hlásit nové stavy přes callback. Každé hlášení se stane další kartou; předchozí zůstává.

Požadavky na váš backend

• HTTPS. Pouze https://, bez http, bez přihlašovacích údajů v adrese, maximálně 2000 znaků.
• Veřejně dostupné. Hostitel se musí vyhodnotit výhradně na veřejné IP adresy. Lokální hostitel, soukromé sítě, link-local a cloudová metadata jsou zamítnuta a toto se kontroluje při každém volání.
• Pevná adresa. Skava vyhodnotí hostitele jednou a připojení připne k této IP adrese. Změna DNS během volání nemá žádný vliv.
• Bez přesměrování. Přesměrování 301 na „správnou“ adresu se počítá jako chyba. Zadejte konečnou adresu hned.
• Čas odezvy. Časový limit je nastavitelný pro každý prvek a pevně omezen na 30 sekund. Pokud potřebujete delší čas, odpovězte okamžitě a výsledek nahlaste později přes callback.
• Velikost odpovědi. Skava načte maximálně 256 KiB.
• Content-Type. Tělo se zpracovává pouze s application/json.

Požadavek, který k vám dorazí

Metoda je GET, POST, PUT nebo PATCH, v závislosti na prvku. Při POST, PUT a PATCH hodnoty přicházejí jako JSON tělo, při GET jako parametry dotazu.

Ověřování je jeden hlavičkový řádek, jehož název a předpona hodnoty jsou nastaveny v prvku, obvykle Authorization s předponou Bearer . Token je u nás uložen zašifrovaně. Hlavičky host, content-length, content-type, cookie a accept-encoding nelze nastavit.

Tělo je plochý objekt. Klíče si vybírá ten, kdo element vytvořil; vnoření se objeví jen tam, kde přidali tabulku nebo výbě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": "…"}

Tři klíče vždy pocházejí od nás, takže je nepoužívejte sami:

• locale: jazykový kód uživatele. Odpovídejte v tomto jazyce; vaše texty nepřekládáme.
• callback_url a callback_token: zpětné volání pro toto jedno interakce, viz níže. Jsou přítomny pouze tehdy, když volání pochází z chatu.

Kontextová pole, jako jsou jméno, firma, projekt nebo subchat, vyplní sám server na základě kanálu, ve kterém byl element spuštěn. Upravený klient tam nemůže tvrdit jiné jméno projektu.

Odpověď: formát karty

Odpovězte kódem 2xx a objektem card. Přesně to se stane kartou v chatu:

{"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 (povinné): celé číslo 1. Jako text ("1") se zamítne. Bez něj se odpověď nepočítá jako karta a použije se mapování odpovědí nakonfigurované v elementu.
• title: nadpis karty.
• state: pouze barva a tón ikony, jedna z hodnot ok, pending, warn, error. Neznámá hodnota se vrátí na ok a dostanete upozornění.
• status_text: volitelný text, který neinterpretujeme. Nachází se v horní části karty a zobrazuje se také v seznamu chatů a v push notifikaci.
• fields: seznam položek label a value. Maximálně 20 záznamů, label 80 znaků, value 200, title a status_text po 120. Příliš dlouhé hodnoty se zkracují, ne zamítají: objednávka by neměla selhat kvůli detailu.
• icon: viz níže.

Co Skava provede s vašimi texty, než se dostanou do chatu: odstraňuje zalomení řádků a ovládací znaky (znak pro psaní zprava doleva by jinak mohl otočit zobrazení částky), nahrazuje backticks a neutralizuje vše, co začíná na [SKAVA:. Poslední bod zabraňuje tomu, aby se hodnota karty četla jako jiný prvek chatu, například jako žádost o platbu.

Odkazy v polích, HTML a obrázky nelze nastavit. Chat je důvěryhodné prostředí a klikací adresa ze zahraničního backendu by byla pozvánkou k přestavbě přihlašovací stránky.

Vstupy uživatele patří na server: zobrazují se na první kartě a nelze je přepsat. V chatu představují záznam toho, co bylo skutečně odesláno.

Ikony

Pomocí icon získá karta vlastní označení v hlavičce. Dva způsoby:

Název ze zabudované sady: 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.

Nebo vlastní SVG jako řetězec. Skava z něj bere pouze geometrii (path, circle, ellipse, rect, line, polyline, polygon včetně jejich číselných atributů) a sestaví vlastní obrázek. Skripty, styly, externí odkazy, foreignObject a atributy událostí se zahodí; doctype nebo entity vedou k odmítnutí; soubor může mít maximálně 8 KiB a obsahovat maximálně 16 tvarů. Barvu, tloušťku linky a velikost nastavuje Skava, takže se ikona nemůže maskovat jako ovládací prvek. Pracujte na mřížce 24 x 24.

Bez icon zůstává výchozí značka.

Kallback: hlášení pozdějších stavů

Volání obsahuje callback_url a callback_token. Použijte je k hlášení nových stavů později:

POST <callback_url> s hlavičkami Authorization: Bearer <callback_token> a Content-Type: application/json, tělo maximálně 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}

Kromě karty existují tři volitelné hodnoty:

• seq: vlastní počítadlo. Zpráva s menší nebo stejnou hodnotou se zahodí, aby se dvě zprávy nemohly předjet. Bez seq platí ta, která dorazí jako poslední.
• final: uzavře interakci. Token se stává neplatným a žádné další karty se nezobrazí. Povolené je i v první odpovědi, pro průběhy bez následných kroků.
• notify: nastavte na false, pokud má být karta odeslána potichu, bez počtu nepřečtených zpráv a bez notifikace. Pro mezikroky, které by neměly nikoho budit. Bez tohoto nastavení je karta naprosto běžnou zprávou.

Každá zpráva se stane vlastní kartou v chatu, předchozí zůstává. Tím je čitelné, který stav byl nahlášen. Z toho vyplývá doporučení: posílejte jen to, co se změnilo. Karta, která čtvrtýkrát opakuje číslo objednávky, položky a celkovou částku, je pro čtenáře jen šum.

Dvě omezení: stejná zpráva dvakrát nevytvoří druhou kartu a jedna interakce může odeslat maximálně 50 karet. Interakce přijímá zprávy po dobu 90 dnů.

Odpovědi, na které byste měli reagovat

• 200 s {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Čtěte nápovědy: uvádějí, co bylo zkráceno nebo vynecháno.
• 401: špatný token nebo ID interakce. Neopakujte požadavek.
• 410: interakce byla uzavřena nebo vypršela. Neopakujte požadavek.
• 422: karta není použitelná, důvod je v hints. Nejprve to opravte.
• 400 poškozené JSON, 413 příliš velký obsah, 429 příliš mnoho požadavků (opakovat s odstupem), 500 chyba na naší straně, zkuste to později.

Příklad 1: objednávka s historií stavů

Krok 1, požadavek na váš backend:

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, vaše okamžitá odpověď:

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

Chat nyní zobrazuje kartu s ikonou balíku, stavem a vstupy uživatele.

Krok 3, později při výběru:

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

Tichá druhá karta bez polí: změnil se pouze stav.

Krok 4, při expedici:

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}

Tato karta může někoho probudit, proto neobsahuje notify: false.

Krok 5, při doručení:

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

Pomocí final se interakce uzavře a token již nefunguje.

Příklad 2: akce bez následných kroků

Ne každý průběh má historii. Prvek s jedním polem, který předává něco do vašeho systému, potřebuje jen jednu odpověď:

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

Zde je důležité final: true: jinak by interakce zůstala otevřená po dobu 90 dnů s platným tokenem, i když už nic neohlásíte.

Výběr produktu z katalogu

Jakmile společnost nahraje svůj katalog článků, může prvek obsahovat blok výběr produktu. Uživatel z něj sestaví košík a vy ho obdržíte jako seznam pod klíčem, který zvolil ten, kdo prvek vytvořil:

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

Protože klíč je volitelný, hledejte první seznam s tímto tvarem, nikoli pevně dané jméno. Před odesláním Skava ověří, že každé číslo skutečně existuje v katalogu dané společnosti, maximálně 50 položek. V kartě se položky zobrazí jako seznam s obrázkem produktu, názvem a množstvím.

Testování

• Ping v editoru prvku odešle holé HEAD bez tokenu a bez dat. Odpovězte čímkoli, jakákoli HTTP odpověď se počítá jako dosažitelnost.
• Testovací požadavek spustí skutečné volání s ukázkovými hodnotami, i když je prvek stále v konceptu, a zobrazí požadavek, odpověď a zprávy validátoru karty.
• Náhled na záložce vedle: vložte svůj JSON odpovědi, zkontrolujte a uvidíte hotovou kartu včetně nápověd. Kontrola probíhá na serveru stejným kódem jako v produkci.
• Příklad serveru: kompletní ukázkový dodavatel běží na api.skava.io a využívá vše výše popsané. Jeho zdrojový kód najdete v repozitáři ve složce example_order_server/, jde zhruba o 600 řádků čistě standardní knihovny, určených k zkopírování.

Co dalšího byste měli vědět

• Karta je úplně běžnou chatovací zprávou. Vyhledá se, lze ji citovat a zůstává v historii.
• Posílá ji systémový odesílatel, ne účet vaší firmy. Přesto se zobrazí na straně toho, kdo prvek spustil, a v titulku je uvedeno, který systém píše.
• Kdo ho může spouštět, je nastaveno na prvku: pouze členové firmy nebo také externí osoby, které s ním sdílejí chat. Když vaše firma chat opustí, oprávnění automaticky skončí.
• API prvek s vypršlým tokem je v klidovém režimu: aktuální aplikace ho skryjí v menu a volání, které se přesto odešle, bude na serveru zamítnuto. Administrátor pro něj uloží nový token, což funguje i u uvolněného rozhraní.

Související

Vytváření a uvolňování: Vlastní prvky: API rozhraní. Vyplňované dokumenty místo rozhraní: Vlastní prvky: Dokumenty.