Ši puslapis skirtas kūrėjams, kurie jungia įmonės galinę sistemą prie Skava. Kaip sukurti ir išleisti API elementą, aprašyta puslapyje Custom Elements: API sąsajos; čia aptariame viską, kas turi įvykti kitoje linijos pusėje.

Idėja vienu sakinio: Skava nežino jūsų srities. Ji žino tik vieną formatą – kortelę. Jūs nuspręsite, ką ji sako, mes tikriname tik formą, dydį ir saugumą. Vienas pavyzdys – medžiagų užsakymas; kita įmonė renka vartotojų atsiliepimus, o dar kita į savo archyvus įkelia statybvietės nuotrauką.

Proceso apžvalga

1. Įmonės administratorius Skava sukuria API elementą: formą bei jūsų galinės sistemos adresą, metodą ir žetoną.
2. Kas nors pokalbyje užpildo formą ir ją siunčia.
3. Skava skambina jūsų galiniam serveriui ir siunčia užpildytas reikšmes kaip JSON.
4. Jūsų atsakymas tampa kortele pokalbyje.
5. Pasirinktinai vėliau galite pranešti apie naujas būsenas per grįžtamąjį ryšį. Kiekvienas pranešimas tampa kita kortele; ankstesnė lieka vietoje.

Reikalavimai jūsų galiniam serveriui

• HTTPS. Tik https://, be http, be prisijungimo duomenų adrese, ne daugiau kaip 2000 simbolių.
• Pasiekiamas viešai. Hostas turi būti išskirtinai susietas su viešais IP adresais. Vietinis hostas, privatus tinklas, ryšio vietos ir debesijos metaduomenys yra atmesti, ir tai tikrinama kiekvieno kvietimo metu.
• Fiksuotas adresas. Skava hostą išsprendžia vieną kartą ir fiksuoja ryšį prie to IP. DNS pokytis kvietimo metu neturi įtakos.
• Nėra nukreipimų. 301 nukreipimas į „teisingą" adresą yra laikomas nesėkme. Įveskite galutinį adresą iškart.
• Atnašos laikas. Laiko limitas yra konfigūruojamas kiekvienam elementui ir griežtai apribotas 30 sekundžių. Jei reikia ilgiau, atsakykite iškart ir vėliau per grįžtamąjį kvietimą praneškite rezultatą.
• Atnašos dydis. Skava perskaito ne daugiau kaip 256 KiB.
• Content-Type. Kūnas yra skaitomas tik su application/json.

Jums atsiųstas užklausos

Metodas yra GET, POST, PUT arba PATCH, priklausomai nuo elemento. Su POST, PUT ir PATCH reikšmės atkeliauja kaip JSON kūnas, su GET – kaip užklausos parametrai.

Patvirtinimas yra vienas antraštės elementas, kurio pavadinimas ir reikšmės priešdėlis yra konfigūruojami elemente, paprastai Authorization su priešdėliu Bearer . Žetonas yra saugomas užšifruotas mūsų pusėje. Antraščių host, content-length, content-type, cookie ir accept-encoding negalima nustatyti.

Kūnas yra plokščias objektas. Rakelius pasirenka tas, kas sukūrė elementą; įdėtiniai lygiai atsiranda tik ten, kur jie pridėjo lentelę arba produkto pasirinktuvą:

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

Tris raktus visada pateikiame mes, todėl jų nenaudokite patys:

• locale: vartotojo kalbos kodas. Atsakykite ta kalba; jūsų tekstų neversliame.
• callback_url ir callback_token: grįžtamasis ryšys šiam vienam sąveikos aktui, žr. žemiau. Jie yra tik tada, kai kvietimas ateina iš pokalbio.

Konteksto laukai, tokie kaip name, company, project ar subchat, yra užpildomi paties serverio, remiantis kanalu, kuriame buvo paleistas elementas. Pakeistas klientas negali ten teigti, kad tai kitas projekto pavadinimas.

Atsakymas: kortelės formatas

Atsakykite 2xx ir card objektu. Būtent tai tampa kortele pokalbyje:

{"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 (privaloma): sveikasis skaičius 1. Jei pateikiamas kaip tekstas ("1"), jis atmestas. Be šio lauko atsakymas nelaikomas kortele ir taikomas elemente sukonfigūruotas atsakymo žemėlapis.
• title: kortelės antraštė.
• state: tik spalva ir ikonos atspalvis, vienas iš ok, pending, warn, error. Jei nurodyta nežinoma reikšmė, naudojama ok ir gaunate įspėjimą.
• status_text: laisvas tekstas, kurio neinterpretuojame. Jis rodomas kortelės viršuje, taip pat matomas pokalbių sąraše ir pranešime.
• fields: sąrašas su label ir value. Daugiausia 20 įrašų, label iki 80 simbolių, value iki 200, title ir status_text po 120. Per ilgi reikšmės yra trumpinamos, o ne atmestos: užsakymas neturi žlugti dėl smulkmenos.
• icon: žr. žemiau.

Ką Skava daro su jūsų tekstu prieš jį atsiunčiant į pokalbį: pašalinami eilučių pertraukos ir valdymo simboliai (dešinės į kairę simbolis kitaip galėtų apversti sumos rodymą), keičiami atvirkštiniai kabliukai, o viskas, prasidedanti [SKAVA:, yra neutralizuojama. Paskutinis žingsnis neleidžia kortelės reikšmei būti supainiotai su kitu pokalbio elementu, pavyzdžiui, mokėjimo prašymu.

Nuorodos laukuose, HTML ir vaizduose nustatyti negalima. Pokalbis yra patikima aplinka, o paspaudžiamas adresas iš svetimo galinio galo būtų kvietimas sukurti naują prisijungimo puslapį.

Vartotojo įvestys priklauso serveriui: jos atsiranda pirmoje kortelėje ir jų negalite perrašyti. Pokalbyje tai yra įrašas apie tai, kas iš tikrųjų buvo pateikta.

Piktogramos

Su icon kortelė gauna savo žymę antraštėje. Du būdai:

Pavadinimas iš įtraukto rinkinio: 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.

Arba jūsų paties SVG kaip eilutė. Iš jo Skava paima tik geometriją (path, circle, ellipse, rect, line, polyline, polygon su jų skaitiniais atributais) ir sukuria savo vaizdą. Skriptai, stiliai, išoriniai nuorodos, foreignObject ir įvykių atributai yra atmesti; dokumento tipas arba entitetas sukelia atmetimą; failas gali būti ne didesnis kaip 8 KiB ir turėti ne daugiau kaip 16 formų. Spalvą, linijos storį ir dydį nustato Skava, todėl piktograma negali pasislėpti kaip valdymo elementas. Dirbkite su 24 x 24 tinkleliu.

Be icon lieka numatytoji žymė.

Grįžtamasis ryšys: vėlesnių būsenų pranešimas

Šaukinyje yra callback_url ir callback_token. Naudokite juos vėliau pranešti apie naujas būsenas:

POST <callback_url> su Authorization: Bearer <callback_token> ir Content-Type: application/json, kūnas ne didesnis kaip 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}

Be kortelės yra trys neprivalomi reikšmės:

• seq: jūsų pats skaitliukas. Pranešimas su mažesne arba lygia verte yra atmestas, todėl du pranešimai negali vienas kitą aplenkti. Be seq laimi paskutinis atvykęs.
• final: užbaigia sąveiką. Žetonas tampa negaliojančiu ir jokių kitų kortelių nebeatsiranda. Leidžiama ir pirmajame atsakyme, srautams, kuriems nereikia tolesnių žingsnių.
• notify: nustatykite į false, kad kortelė būtų paskelbta tyliai, be neperskaitytų žinučių skaičiavimo ir be pranešimo. Tinka tarpiniams žingsniams, kuriems nereikia pažadinti nieko. Be šio nustatymo kortelė yra visiškai įprasta žinutė.

Kiekvienas ataskaitos tampa atskira kortele pokalbyje, ankstesnė lieka vietoje. Taip lengviau suprasti, kokia būsena buvo pranešta. Iš to išplaukia rekomendacija: siųskite tik tai, kas pasikeitė. Kortelė, ketvirtą kartą kartojanti užsakymo numerį, prekes ir bendrą sumą, skaitytojui yra tik triukšmas.

Dvi ribos: ta pati ataskaita, siunčiama du kartus, nesukuria antros kortelės, ir sąveika gali paskelbti daugiausia 50 kortelių. Sąveika priima ataskaitas 90 dienų.

Atsakymai, į kuriuos turite reaguoti

• 200 su {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Perskaitykite užuominas: jose nurodoma, kas buvo sutrumpinta arba atmesta.
• 401: neteisingas žetonas arba sąveikos identifikatorius. Nekartokite bandymo.
• 410: sąveika uždaryta arba pasibaigė. Nekartokite bandymo.
• 422: kortelė netinkama naudoti, priežastis nurodyta hints. Pirmiausia ištaisykite.
• 400 sugadintas JSON, 413 per didelis, 429 per daug užklausų (pakartokite su laukimo intervalu), 500 mūsų klaida, pakartokite vėliau.

1 pavyzdys: užsakymas su būsenų istorija

1 žingsnis, užklausa jūsų galinei sistemai:

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

2 žingsnis, jūsų nedelsiant pateiktas atsakymas:

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

Čate dabar rodoma kortelė su siuntos ikona, būsena ir vartotojo įvestimis.

3 žingsnis, vėliau ruošiant siuntą:

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

Tylus antrasis kortelės įrašas be laukų: pasikeitė tik būsena.

4 žingsnis, siunčiant:

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}

Ši kortelė gali pažadinti žmogų, todėl nėra notify: false.

5 žingsnis, pristatant:

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

Su final sąveika užbaigiama ir žetonas nebegalioja.

Pavyzdys 2: veiksmas be tolesnių žingsnių

Ne kiekvienas srautas turi istoriją. Elementui su vienu lauku, kuris perduoda kažką į jūsų sistemą, reikia tik vieno atsakymo:

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

Čia svarbu final: true: kitaip sąveika liktų atvira 90 dienų su galiojančiu žetonu, nors niekada daugiau nieko neberašysite.

Produktų parinkiklis iš katalogo

Kai įmonė įkėlė savo straipsnių katalogą, elemente gali būti produktų parinkiklio blokas. Vartotojas iš jo sudaro krepšelį, o jūs jį gaunate kaip sąrašą pagal raktą, kurį pasirinko elementą sukūręs asmuo:

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

Kadangi raktas yra nemokamas, ieškokite pirmojo sąrašo, turinčio šią struktūrą, o ne fiksuoto pavadinimo. Prieš siųsdami, „Skava" patikrina, ar kiekvienas numeris iš tikrųjų egzistuoja tos įmonės kataloge, ne daugiau kaip 50 elementų. Kortelėje elementai rodomi kaip sąrašas su produkto paveiksliuku, pavadinimu ir kiekiu.

Testavimas

• Elementų redaktoriuje esanti funkcija Ping siunčia tuščią HEAD užklausą be ženklo ir be duomenų. Atsakykite bet kuo; bet koks HTTP atsakymas reiškia, kad paslauga pasiekiama.
• Funkcija Test request atlieka realų kvietimą su pavyzdiniais reikšmėmis, net jei elementas vis dar yra juodraštis, ir rodo užklausą, atsakymą bei kortelės validatoriaus pranešimus.
• Funkcija Preview gretimame skirtuke: įklijuokite savo atsakymo JSON, patikrinkite ir pamatysite paruoštą kortelę bei patarimus. Tai tikrinama serveryje naudojant tą patį kodą kaip ir gamybinėje aplinkoje.
• Pavyzdinis serveris: pilnai veikiantis pavyzdinis tiekėjas veikia adresu api.skava.io ir naudoja viską, kas aprašyta aukščiau. Jo šaltinis yra saugomas saugykloje ašyje example_order_server/, tai apie 600 eilučių grynos standartinės bibliotekos kodas, skirtas nukopijuoti.

Ką dar turėtumėte žinoti

• Kortelė yra visiškai įprasta pokalbio žinutė. Ji atsiranda paieškoje, gali būti cituojama ir lieka istorijoje.
• Ji siunčiama sistemos siuntėjo, o ne jūsų įmonės paskyros. Vis dėlto ji atsiranda to asmens pusėje, kuris paleido elementą, o pavadinime nurodoma, kuri sistema ją parašė.
• Kas gali ją paleisti, nustatoma elemente: tik įmonės nariai arba taip pat išorės asmenys, kurie dalijasi pokalbiu. Kai jūsų įmonė palieka pokalbį, leidimas pasibaigia savaime.
• API elementas su pasibaigusiu galiojimo laikotarpiu yra neaktyvus ir nematomas meniu, kol administratorius įkelia naują.

Susiję

Kūrimas ir leidimas: Custom Elements: API sąsajos. Užpildomi dokumentai vietoj sąsajų: Custom Elements: Dokumentai.