Skava Skava / Wiki

Prisijungti „Custom Elements“ kūrėjams

Ši skirta kūrėjams, kurie jungia įmonės galinį serverį prie Skava. Kaip sukuriamas ir leidžiamas API elementas, aprašyta puslapyje Custom Elements: API sąsajos; čia aptariame viską, kas turi įvykti kitoje linijos pusėje.

Idėja vienu sakinys: Skava nežino jūsų srities. Ji žino tiksliai vieną formatą, kortelę. Jūs nusprendžiate, ką ji sako, mes tikriname tik formą, dydį ir saugumą. Medžiagų užsakymas yra vienas pavyzdys; kita įmonė renka vartotojų atsiliepimus, o dar kita į savo archyvus įkela statybvietės nuotrauką.

Proceso apžvalga

  1. Įmonės administratorius Skava sukuria API elementą: formą ir jūsų galinio serverio adresą, metodą bei žetoną.
  2. Kas nors pokalbyje užpildo formą ir ją išsiunčia.
  3. Skava kreipiasi į jūsų backendą ir siunčia užpildytas reikšmes JSON formatu.
  4. Jūsų atsakymas tampa kortele pokalbyje.
  5. Pasirinktinai vėliau pranešate apie naujas būsenas per callback. Kiekvienas pranešimas tampa kita kortele; ankstesnė lieka.

Reikalavimai jūsų backendui

  • HTTPS. Tik https://, be http, be prisijungimo duomenų adrese, daugiausia 2000 simbolių.
  • Pasiekiamas viešai. Serveris turi būti susietas tik su viešais IP adresais. Lokalinis serveris, privačios tinklai, nuorodų vietiniai adresai ir debesų metaduomenys yra atmetami, o tai tikrinama kiekvieno kvietimo metu.
  • Fiksuotas adresas. Skava serverį išsprendžia tik kartą ir fiksuoja ryšį su tuo IP adresu. DNS pokyčiai kvietimo metu neturi įtakos.
  • Be peradresacijų. 301 peradresacija į „teisingą“ adresą laikoma klaida. Įveskite galutinį adresą iš karto.
  • Atsakymo laikas. Laiko limitas konfigūruojamas kiekvienam elementui atskirai ir yra ribotas 30 sekundžių. Jei reikia ilgesnio laiko, atsakykite iš karto ir praneškite rezultatą vėliau per grįžtamąjį kvietimą.
  • Atsakymo dydis. Skava skaito ne daugiau kaip 256 KiB.
  • Content-Type. Kūnas skaidomas tik su application/json.

Prašymas, kuris pasiekia jus

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

Autentifikacija yra vienas antraštės laukas, kurio pavadinimas ir reikšmės prefiksas nustatomi elemente, paprastai Authorization su prefiksu Bearer . Žetonas saugomas šifruotu mūsų pusėje. Antraštės host, content-length, content-type, cookie ir accept-encoding negali būti nustatytos.

Kūnas yra plokščias objektas. Raktus pasirenka elementą sukūręs asmuo; įdubos atsiranda tik ten, kur pridėta lentelė ar produkto parinktuvas:

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

Trys raktai visada ateina iš mūsų, todėl jų naudokite patys:

  • locale: vartotojo kalbos kodas. Atsakykite ta kalba; jūsų tekstų nevertiname.
  • callback_url ir callback_token: šios vienos sąveikos grąžinamasis ryšys, žr. žemiau. Jie yra tik tada, kai kvietimas ateina iš pokalbio.

Konteksto laukai, tokie kaip vardas, įmonė, projektas ar pokalbio šakelė, užpildomi paties serverio, išvedami iš kanalo, kuriame elementas buvo paleistas. Pakeistas klientas negali ten reikalauti kito projekto pavadinimo.

Atsakymas: kortelės formatas

Atsakykite su 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. Tekstu ("1") jis yra atmestas. Be šio lauko atsakymas nelaikomas kortele ir taikomas elemente nustatytas atsakymų atvaizdavimas.
  • title: kortelės antraštė.
  • state: tik spalva ir ikonos atspalvis, vienas iš ok, pending, warn, error. Nežinoma reikšmė grąžinama kaip ok ir gaunate priminimą.
  • status_text: laisvas tekstas, kurio neinterpretuojame. Jis rodomas kortelės viršuje, taip pat matomas pokalbių sąraše ir pranešimuose.
  • fields: sąrašas su label ir value. Daugiausia 20 įrašų, label iki 80 simbolių, value iki 200, title ir status_text po 120 simbolių. Per ilgos reikšmės yra trumpinamos, o ne atmestos: užsakymas neturėtų nepavykti dėl smulkmenos.
  • icon: žr. žemiau.

Ką Skava daro su jūsų tekstu prieš jį atsiunčiant į pokalbį: eilučių perėjimai ir valdymo simboliai pašalinami (kairėn į dešinę rašomas simbolis kitaip galėtų apversti sumos rodymą), atvirkštinės kabutės pakeičiamos, o viskas, kas prasideda nuo [SKAVA:, neutralizuojama. Paskutinis dalykas apsaugo nuo to, kad kortelės reikšmė būtų suvokiama kaip kitas pokalbio elementas, pavyzdžiui, mokėjimo prašymas.

Sąsajos laukuose, HTML ir vaizdai negali būti nustatomi. Pokalbis yra patikima aplinka, o spustelėjama adresas iš svetainės galėtų būti kvietimas iš naujo kurti prisijungimo puslapį.

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

Piktogramos

Su icon kortelė gauna savo ženklo antraštėje. Dvi būdai:

Pavadinimas iš komplekto 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ų SVG kaip eilutė. Iš jos Skava naudoja tik geometriją (path, circle, ellipse, rect, line, polyline, polygon su jų skaitinėmis savybėmis) ir sukuria savo vaizdą. Skriptai, stiliai, išorinės nuorodos, foreignObject ir įvykių savybės yra pašalinamos; dokumento tipas ar entitetas lemia atmetimą; failas gali būti ne didesnis nei 8 KiB ir turėti ne daugiau kaip 16 formų. Spalvą, linijos storį ir dydį nustato Skava, todėl piktograma negali apsimesti valdikliu. Dirbkite su 24 x 24 tinkleliu.

Be icon lieka numatytoji žymė.

Atsakymo funkcija: vėlesnių būsenų pranešimas

Kvietime 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 nepriklausomi reikšmės:

  • seq: jūsų skaičiuoklė. Ataskaita su mažesne arba lygia reikšme yra atmesta, todėl dvi ataskaitos negali viena kitos aplenkti. Be seq laimėja ta, kuri atvyksta paskutinė.
  • final: užbaigia sąveiką. Žetonas tampa nebeveikiamas ir daugiau kortelių nebeatsiranda. Taip pat leidžiama pirmajame first atsakyme, procesams, kuriems nereikia tolesnių žingsnių.
  • notify: nustatykite false, kad kortelė būtų išsiųsta tyliai, be neskaitytų žinučių skaičiaus ir be pranešimo. Tinka tarpiniams žingsniams, kurie neturėtų nieko pabudinti. Be šio nustatymo kortelė yra visiškai įprasta žinutė.

Kiekviena ataskaita tampa atskira kortele čate, o ankstesnė lieka. Taip aišku, kokia būsena buvo pranešta. Iš to seka rekomendacija: siųskite tik tai, kas pasikeitė. Kortelė, ketvirtą kartą kartojanti užsakymo numerį, prekes ir sumą, skaitytojui yra tik triukšmas.

Du apribojimai: tas pats ataskaitos įrašas du kartus nesukuria antro kortelės, o viena sąveika gali pateikti ne daugiau kaip 50 kortelių. Sąveika priima ataskaitų įrašus 90 dienų.

Atsakymai, į kuriuos turėtumėte reaguoti

  • 200 su {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Skaitykite pastabas: jose nurodoma, kas buvo sutrumpinta arba pašalinta.
  • 401: neteisingas žetonas arba sąveikos identifikatorius. Nebandykite dar kartą.
  • 410: sąveika uždaryta arba pasibaigė. Nebandykite dar kartą.
  • 422: kortelė negali būti naudojama, priežastis nurodyta laukelyje hints. Pirmiausia ją ištaisykite.
  • 400 sugadintas JSON, 413 per didelis, 429 per daug užklausų (bandykite iš naujo su laukimu), 500 mūsų klaida, bandykite vėliau.

Pavyzdys 1: užsakymas su būsenos istorija

1 žingsnis, užklausa į jūsų 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"}

2 žingsnis, jūsų nedelsiamas 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 pakuotės piktograma, būsena ir vartotojo įvestimi.

3 žingsnis, vėliau pasirinkimo metu:

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

Rami antra kortelė be laukų: pasikeitė tik būsena.

4 žingsnis, išsiuntimo metu:

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 ir pabudinti, todėl nenaudojama notify: false.

5 žingsnis, pristatymo metu:

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ždaroma ir žetonas nebeveikia.

Pavyzdys 2: veiksmas be tolesnių žingsnių

Ne kiekviena eiga turi istoriją. Elementui su vienu lauku, kuris perduoda duomenis jūsų sistemai, pakanka 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 nieko daugiau nebepraneštumėte.

Prekių pasirinkimas iš katalogo

Kai įmonė įkelia savo straipsnių katalogą, elemente gali būti naudojamas prekių pasirinkimo blokas. Vartotojas iš jo sudaro krepšelį, o jūs gaunate jį sąrašo pavidalu pagal raktą, kurį pasirinko elementą sukūręs asmuo:

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

Kadangi raktas yra laisvas, ieškokite pirmojo sąrašo, turinčio šią struktūrą, o ne fiksuoto pavadinimo. Prieš siųsdama, Skava patikrina, ar kiekvienas numeris tikrai egzistuoja tos įmonės kataloge, ne daugiau kaip 50 prekių. Kortelėje prekės rodomos sąraše su prekių vaizdu, pavadinimu ir kiekiu.

Testavimas

  • Ping elemento redaktoriuje siunčia paprastą HEAD užklausą be žetono ir be duomenų. Atsakykite bet kuo; bet koks HTTP atsakymas laikomas pasiekiamu.
  • Testo užklausa atlieka tikrąjį kvietimą su pavyzdinėmis reikšmėmis, net jei elementas dar yra juodraštis, ir rodo užklausą, atsakymą bei kortelės validatoriaus pranešimus.
  • Peržiūra gretimame skirtuke: įklijuokite savo atsakymo JSON, patikrinkite ir pamatysite baigtą kortelę bei užuominas. Serveris patikrina tą pačią kodą, kuris naudojamas gamyboje.
  • Pavyzdinis serveris: pilnas pavyzdinis tiekėjas veikia api.skava.io ir naudoja viską, kas aprašyta aukščiau. Jo šaltinis yra saugyklos kataloge example_order_server/, apie 600 eilučių gryno standartinės bibliotekos kodo, skirtas kopijavimui.

Ką dar turėtumėte žinoti

  • Kortelė yra visiškai įprasta pokalbio žinutė. Ji randama paieškoje, gali būti cituojama ir lieka istorijoje.
  • Ją siunčia sistemos siuntėjas, o ne jūsų įmonės paskyra. Ji vis tiek rodoma to pusėje, kuris paleido elementą, o pavadinime nurodoma, kuri sistema rašo.
  • Kas gali jį naudoti, nustatoma elemente: tik įmonės nariai arba ir išoriniai asmenys, kurie dalijasi juo pokalbyje. Kai jūsų įmonė palieka pokalbį, leidimas baigiasi automatiškai.
  • API elementas su pasibaigusiu galiojimu žymuo yra neveiklus: esamos programos jį slepia meniu, o išsiųstas skambutinys atmetamas serverio pusėje. Administratorius jame saugo naują žymą, kuri veikia ir išleistoje sąsajoje.

Susiję

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