Táto stránka je určená vývojárom, ktorí spájajú backend firmy so Skava. Ako sa vytvára a uvoľňuje API prvok, je popísané na stránke Vlastné prvky: rozhrania API; tu pokrývame všetko, čo sa musí stať na druhej strane spojenia.

Myšlienka v jednej vete: Skava nevie o vašom odbore. Pozná presne jeden formát, a to kartu. Vy rozhodnete, čo bude obsahovať, my kontrolujeme iba tvar, veľkosť a bezpečnosť. Jedným príkladom je objednávka materiálu; ďalšia firma zbiera spätnú väzbu od používateľov, ďalšia zase archivuje fotografiu stavby vo svojich záznamoch.

Priebeh v skratke

1. Administrátor firmy vytvorí v Skava API prvok: formulár plus adresu vášho backendu, metódu a token.
2. Niekto v čate vyplní formulár a odošle ho.
3. Skava volá váš backend a odosiela vyplnené hodnoty ako JSON.
4. Vaša odpoveď sa stane kartou v čate.
5. Voliteľne môžete neskôr hlásiť nové stavy prostredníctvom callbacku. Každé hlásenie sa stane ďalšou kartou; predchádzajúca zostane.

Požiadavky na váš backend

• HTTPS. Iba https://, žiadne http, žiadne prihlasovacie údaje v adrese, maximálne 2000 znakov.
• Verejne dostupné. Hostiteľ sa musí vyriešiť výlučne na verejné IP adresy. Lokálne adresy, súkromné siete, link-local adresy a cloudové metadáta sú zamietnuté a toto sa kontroluje pri každom volaní.
• Fixná adresa. Skava vyrieši hostiteľa raz a pripojenie sa viaže na túto IP adresu. Zmena DNS počas volania nemá žiadny efekt.
• Žiadne presmerovania. Presmerovanie 301 na „správnu“ adresu sa považuje za zlyhanie. Zadajte konečnú adresu hneď.
• Čas odozvy. Časový limit je pre každý prvok nastaviteľný a tvrdým limitom je 30 sekúnd. Ak potrebujete dlhší čas, odpovedzte okamžite a výsledok nahláste neskôr prostredníctvom spätného volania.
• Veľkosť odozvy. Skava prečíta maximálne 256 KiB.
• Content-Type. Telo sa vyhodnocuje iba s application/json.

Žiadosť, ktorá k vám dorazí

Metóda je GET, POST, PUT alebo PATCH v závislosti od prvku. Pri POST, PUT a PATCH hodnoty prichádzajú ako JSON telo, pri GET ako parametre dotazu.

Overenie totožnosti je jedna hlavička, ktorej názov a predpona hodnoty sú nakonfigurované v prvku, zvyčajne Authorization s predponou Bearer . Token je na našej strane uložený zašifrovaný. Hlavičky host, content-length, content-type, cookie a accept-encoding nemožno nastaviť.

Telo je rovný objekt. Kľúče vyberá tvorca prvku; vnožovanie sa objavuje len tam, kde pridal tabuľku alebo výber 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": "…"}

Tri kľúče vždy pochádzajú od nás, preto ich nepoužívajte sami:

• locale: jazykový kód používateľa. Odpovedajte v tomto jazyku; vaše texty neklademe do slovenčiny.
• callback_url a callback_token: spätné volanie pre túto jednu interakciu, pozri nižšie. Sú prítomné len vtedy, keď volanie prichádza z chatu.

Kontextové polia, ako sú meno, firma, projekt alebo podkonverzácia, sa vyplnia samotným serverom na základe kanála, v ktorom bol prvok spustený. Zmenený klient sa tam nemôže tváriť, že ide o iný názov projektu.

Odpoveď: formát karty

Odpovedzte s 2xx a objektom card. Presne toto sa stane kartou v čate:

{"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. Ako text ("1") sa zamietne. Bez neho sa odpoveď nepovažuje za kartu a použije sa mapovanie odpovede nakonfigurované v prvku.
• title: nadpis karty.
• state: iba farba a odtieň ikony, jedna z možností ok, pending, warn, error. Neznáma hodnota sa prepne na ok a dostanete upozornenie.
• status_text: voľný text, ktorý neinterpretujeme. Nachádza sa v hornej časti karty a zobrazuje sa aj v zozname chatov a v push notifikácii.
• pole: zoznam label a value. Maximálne 20 položiek, label 80 znakov, value 200, title a status_text po 120. Príliš dlhé hodnoty sa skrácia, nie sa zamietnu: objednávka by nemala zlyhať kvôli detailu.
• ikonka: pozri nižšie.

Čo Skava urobí s vašimi textmi, než dorazia do chatu: odstránia sa zalomenia riadkov a riadiace znaky (znak zprava doľava by inak mohol prevrátiť zobrazenie sumy), prepíšu sa spätné úvodzovky a všetko začínajúce na [SKAVA: sa neutralizuje. Posledné opatrenie zabraňuje tomu, aby sa hodnota karty čítala ako iný prvok chatu, napríklad ako žiadosť o platbu.

Odkazy v poliach, HTML a obrázky nemožno nastaviť. Chat je dôveryhodné prostredie a klikateľná adresa z cudzieho backendu by bola pozvánkou na obnovenie prihlasovacej stránky.

Vstupy používateľa patria serveru: objavujú sa na prvej karte a nemožno ich prepísať. V chate predstavujú záznam toho, čo bolo skutočne odoslané.

Ikony

Pomocou icon dostane karta vlastnú značku v hlavičke. Dve možnosti:

Názov z balíka: 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.

Albo vlastný SVG ako reťazec. Skava z neho vezme iba geometriu (path, circle, ellipse, rect, line, polyline, polygon s ich číselnými atribútmi) a vytvorí vlastný obrázok. Skripty, štýly, externé odkazy, foreignObject a atribúty udalostí sa zahodia; doctype alebo entita vedie k zamietnutiu; súbor môže mať maximálne 8 KiB a obsahovať najviac 16 tvarov. Farbu, hrúbku čiary a veľkosť nastavuje Skava, takže ikona sa nemôže maskovať ako ovládací prvok. Pracujte s mriežkou 24 x 24.

Bez icon zostáva predvolená značka.

Spätné volanie: nahlásenie neskorších stavov

Volanie obsahuje callback_url a callback_token. Použite ich na nahlásenie nových stavov neskôr:

POST <callback_url> s Authorization: Bearer <callback_token> a Content-Type: application/json, telo najviac 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}

Okrem karty existujú tri voliteľné hodnoty:

• seq: váš vlastný počítadlo. Správa s menšou alebo rovnakou hodnotou sa zahodí, aby sa dve správy nemohli predbiehať. Bez seq vyhráva tá, ktorá príde naposledy.
• final: ukončuje interakciu. Token sa stáva neplatným a ďalšie karty sa už nezobrazia. Je povolený aj v prvej odpovedi pre tok bez následných otázok.
• notify: nastavením na false sa karta zverejní ticho, bez počítadla neprečítaných správ a bez upozornenia. Ideálne pre medzikroky, ktoré by nemali nikoho prebudiť. Bez tohto parametra je karta úplne bežnou správou.

Každá správa sa stane samostatnou kartou v čate, predchádzajúca zostane. Takto je zrejmé, ktorý stav bol nahlásený. Z toho vyplýva odporúčanie: zasielať len to, čo sa zmenilo. Karta, ktorá po štvrtýkrát opakuje číslo objednávky, položky a celkovú sumu, je pre čitateľa len hluk.

Dva limity: rovnaká správa dvakrát nevytvorí druhú kartu a interakcia môže zverejniť najviac 50 kariet. Interakcia prijíma správy počas 90 dní.

Odpovede, na ktoré by ste mali reagovať

• 200 s {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Prečítajte si nápovede: uvádzajú, čo bolo skrátené alebo vynechané.
• 401: nesprávny token alebo ID interakcie. Neopakujte pokus.
• 410: interakcia bola uzavretá alebo vypršala. Neopakujte pokus.
• 422: karta je nepoužiteľná, dôvod je v nápovedách. Najprv to opravte.
• 400 poškodený JSON, 413 príliš veľké, 429 príliš veľa požiadaviek (opakujte s oneskorením), 500 naša chyba, skúste to neskôr.

Príklad 1: objednávka s históriou stavov

Krok 1, požiadavka 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ša okamžitá odpoveď:

{"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 teraz zobrazuje kartu s ikonou balíka, stavom a vstupmi používateľa.

Krok 3, neskôr pri zbere:

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í: zmenil sa iba stav.

Krok 4, pri expedícii:

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}

Táto karta môže niekoho prebudiť, preto nie je nastavené notify: false.

Krok 5, pri 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 interakcia uzavretá a token už nefunguje.

Príklad 2: akcia bez následných krokov

Nie každý tok má históriu. Prvok s jedným poľom, ktorý niečo odovzdáva vášmu systému, potrebuje iba jednu odpoveď:

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

Tu je dôležitý final: true: inak by interakcia zostala otvorená 90 dní s platným tokenom, hoci už nikdy nič neohlásite.

Výber produktu z katalógu

Akonáhle firma nahrala svoj katalóg položiek, prvok môže obsahovať blok výber produktu. Používateľ z neho zostaví košík a vy ho dostanete ako zoznam pod kľúčom, ktorý si vybral tvorca prvku:

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

Keďže kľúč je voľný, hľadajte prvý zoznam s touto štruktúrou, nie pevný názov. Pred odoslaním Skava overí, či každé číslo skutočne existuje v katalógi danej firmy, maximálne 50 položiek. V karte sa položky zobrazia ako zoznam s obrázkom produktu, názvom a množstvom.

Testovanie

• Ping v editorovi elementu odosiela čistý HEAD bez tokena a bez dát. Odpovedzte čokoľvek; akákoľvek HTTP odpoveď sa považuje za dostupnú.
• Testovacia požiadavka spustí skutočné volanie so vzorovými hodnotami, aj keď je element stále v koncepte, a zobrazí požiadavku, odpoveď a správy overovateľa karty.
• Náhľad na susednej karte: vložte svoju odpoveď JSON, overte a uvidíte dokončenú kartu spolu s nápovedami. Overenie sa vykonáva na serveri rovnakým kódom ako v produkčnom prostredí.
• Príkladový server: kompletný príkladový dodávateľ beží na api.skava.io a využíva všetko vyššie popísané. Jeho zdrojový kód sa nachádza v repozitári v priečinku example_order_server/, ide o približne 600 riadkov čistej štandardnej knižnice, určených na kopírovanie.

Čo ešte by ste mali vedieť

• Karta je úplne bežnou správou v čate. Zobrazuje sa vo vyhľadávaní, dá sa citovať a zostáva v histórii.
• Posiela ju systémový odosielateľ, nie účet vašej firmy. Stále sa však zobrazuje na strane toho, kto spustil prvok, a v nadpise je uvedené, ktorý systém ju zapisuje.
• Kto prvok môže spustiť, je nastavené na prvku samotnom: len členovia firmy, alebo aj externé osoby, ktoré majú s firmou zdieľaný chat. Keď firma opustí chat, oprávnenie sa automaticky zruší.
• API prvok s expirovaným tokenom je neaktívny a v ponuke sa vôbec nezobrazuje, kým administrátor neuloží nový.

Súvisiace

Vytváranie a uvoľňovanie: Vlastné prvky: rozhrania API. Vyplniteľné dokumenty namiesto rozhraní: Vlastné prvky: dokumenty.