Tato stránka je určena vývojářům, kteří propojují backend firmy se Skavou. Vytváření a vydávání API elementu je popsáno na stránce Vlastní prvky: rozhraní API; zde se věnujeme všemu, co musí proběhnout na druhém konci spojení.

Myšlenka v jedné větě: Skava nezná vaši doménu. Zná přesně jeden formát, a to kartu. Vy rozhodnete, co bude obsahovat, my kontrolujeme pouze tvar, velikost a bezpečnost. Jedním příkladem je objednávka materiálu; další firma shromažďuje zpětnou vazbu od uživatelů, další ukládá fotku stavby do svých záznamů.

Přehled toku

1. Administrátor firmy vytvoří ve Skavě API element: formulář spolu s adresou vašeho backendu, metodou a tokenem.
2. Někdo v chatu vyplní formulář a odešle ho.
3. Skava volá vaše backend a odesílé 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ůstane.

Požadavky na vaše backend

• HTTPS. Pouze https://, žádný http, žádné přihlašovací údaje v adrese, maximálně 2000 znaků.
• Veřejně dostupné. Hostitel se musí vyřešit výhradně na veřejné IP adresy. Lokální hostitel, soukromé sítě, link-local adresy a cloudová metadata jsou zamítnuta a toto se kontroluje při každém volání.
• Fixní adresa. Skava vyřeší hostitele jednou a připojení připojí k této IP adrese. Změna DNS během volání nemá žádný efekt.
• Žádné přesměrování. Přesměrování 301 na „správnou“ adresu se počítá jako selhání. Zadejte konečnou adresu okamžitě.
• Čas odezvy. Časový limit je konfigurovatelný pro každý prvek a je tvrdě omezen na 30 sekund. Pokud potřebujete delší dobu, odpovězte okamžitě a výsledek nahlásíte později prostřednictvím zpětného volání.
• Velikost odpovědi. Skava přečte maximálně 256 KiB.
• Content-Type. Tělo se analyzuje pouze s application/json.

Žádost, která k vám dorazí

Metoda je GET, POST, PUT nebo PATCH v závislosti na prvku. U POST, PUT a PATCH hodnoty dorazí jako JSON tělo, u GET jako parametry dotazu.

Ověření je jedna hlavička, jejíž název a prefix hodnoty jsou nakonfigurovány v prvku, obvykle Authorization s prefixem Bearer . Token je na naší straně uložen šifrovaný. Hlavičky host, content-length, content-type, cookie a accept-encoding nelze nastavit.

Tělo je rovný objekt. Klíče vybírá ten, kdo prvek vytvořil; vnoření se objevuje pouze 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, proto je nepoužívejte sami:

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

Kontextová pole, jako jsou name, company, project nebo subchat, vyplňuje samotný server na základě kanálu, ve kterém byl prvek spuštěn. Zfalšovaný klient se tam nemůže domluvit na jiném názvu projektu.

Odpověď: formát karty

Odpovězte s 2xx a objektem card. Právě 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") je zamítnuto. Bez něj se odpověď nepočítá jako karta a platí mapování odpovědí nakonfigurované v prvku.
• 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: volný text, který neinterpretujeme. Nachází se v horní části karty a je to také to, co se zobrazí v seznamu chatů a v push notifikaci.
• pole: seznam label a value. Maximálně 20 položek, 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.
• ikon: viz níže.

Co Skava provede s vašimi texty, než dorazí do chatu: odstraní se zalomení řádků a ovládací znaky (znak zprava doleva by jinak mohl převrátit zobrazení částky), zpětné uvozovky se nahradí a vše začínající [SKAVA: se neutralizuje. 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 klikatelná adresa z cizího backendu by byla pozvánkou k obnovení přihlašovací stránky.

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

Ikony

Pomocí icon získá karta vlastní značku v záhlaví. Dvě možnosti:

Název z balíčku: 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 vezme pouze geometrii (path, circle, ellipse, rect, line, polyline, polygon s jejich číselnými atributy) a vytvoří vlastní obrázek. Skripty, styly, externí odkazy, foreignObject a atributy událostí se zahazují; doctype nebo entita způsobí zamítnutí; soubor může mít maximálně 8 KiB a obsahovat nejvýše 16 tvarů. Barvu, šířku čáry a velikost nastavuje Skava, takže ikona se nemůže vydávat za ovládací prvek. Pracujte na mřížce 24 x 24.

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

Zpětné volání: hlášení pozdějších stavů

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

POST <callback_url> s 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: váš vlastní počítadlo. Hlášení s menší nebo stejnou hodnotou se zahodí, takže se dvě hlášení nemohou předjet. Bez seq vyhrává poslední dorazené.
• final: ukončuje interakci. Token se stává neplatným a další karty se již nezobrazí. Je povoleno i v první odpovědi pro průběhy bez následných kroků.
• notify: nastavte na false, pokud chcete kartu odeslat tiše, bez počítadla nepřečtených zpráv a bez upozornění. Vhodné pro mezikroky, které by neměly nikoho rušit. Bez tohoto parametru je karta běžnou zprávou.

Každá zpráva se stane samostatnou kartou v chatu, přičemž předchozí zůstává. Tím je zřejmé, jaký stav byl hlášen. Z toho vyplývá doporučení: odesílejte pouze to, co se změnilo. Karta, která po čtvrté opakuje číslo objednávky, položky a celkovou částku, je pro čtenáře jen hluk.

Dva limity: stejná zpráva dvakrát nevytvoří druhou kartu a 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": []}. Přečtěte si nápovědy: vysvětlují, co bylo zkráceno nebo vynecháno.
• 401: špatný token nebo ID interakce. Nezkoušejte to znovu.
• 410: interakce byla uzavřena nebo vypršela. Nezkoušejte to znovu.
• 422: karta nepoužitelná, důvod v nápovědách. Nejprve to opravte.
• 400 poškozený JSON, 413 příliš velké, 429 příliš mnoho požadavků (zkuste to znovu s odstupem), 500 naše chyba, 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 uživatelskými vstupy.

Krok 3, později při sbě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 není nastaveno 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}

S final je interakce uzavřena 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 vašemu systému, potřebuje pouze 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á hodnota final: true: jinak by interakce zůstala otevřená po dobu 90 dnů s platným tokenem, i když už nikdy nic neohlásíte.

Výběr produktu z katalogu

Jakmile společnost nahraje svůj katalog artiklů, prvek může obsahovat blok výběr produktu. Uživatel z něj sestaví košík a vy jej obdržíte jako seznam pod klíčem, který zvolil tvůrce prvku:

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

Protože klíč je volitelný, hledejte první seznam s tímto tvarem, nikoliv pevně daný název. Před odesláním Skava ověří, že každé číslo skutečně existuje v katalogu dané firmy, 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 elementu odešle holý HEAD bez tokenu ani dat. Odpovězte čímkoliv; jakákoliv HTTP odpověď se počítá jako dosažitelnost.
• Testovací požadavek spustí skutečné volání s ukázkovými hodnotami, i když je element stále v návrhu, a zobrazí požadavek, odpověď a zprávy od validátoru karty.
• Náhled na sousední kartě: vložte svůj JSON s odpovědí, zkontrolujte a uvidíte dokončenou kartu včetně nápověd. Kontrola probíhá na serveru stejným kódem jako v produkci.
• Příklad serveru: kompletní příklad dodavatele běží na api.skava.io a využívá vše výše popsané. Jeho zdrojový kód se nachází v repozitáři v adresáři example_order_server/, jde o zhruba 600 řádků čisté standardní knihovny, připravených k zkopírování.

Co ještě byste měli vědět

• Karta je úplně běžnou zprávou v chatu. Zobrazuje se ve vyhledávání, lze ji citovat a zůstává v historii.
• Je odesílána systémovým odesílatelem, nikoliv účtem vaší firmy. Stále se však zobrazuje na straně toho, kdo prvek spustil, a v nadpisu je uvedeno, který systém ji zapisuje.
• Kdo ji může spustit, je nastaveno na prvku: pouze členové firmy nebo také vnější osoby, které sdílejí chat. Když vaše firma chat opustí, oprávnění samo o sobě skončí.
• Prvek API s vypršalým tokenem je nečinný a v nabídce se neobjeví, dokud správce neuloží nový.

Související

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