Skava Skava / Wiki

Kobling av tilpassede elementer for utviklere

Denne siden er for utviklere som kobler et selskaps backend til Skava. Hvordan et API-element opprettes og publiseres, behandles på Tilpassede elementer: API-grensesnitt. Her dekker vi alt som må skje på den andre enden av linjen.

Ideene på én setning: Skava kjenner ikke ditt fagområde. Den kjenner nøyaktig ett format, kortet. Du bestemmer hva det sier, vi sjekker bare form, størrelse og sikkerhet. En materialbestilling er ett eksempel. Neste selskap samler inn brukertilbakemeldinger, og det neste arkiverer et bilde av byggeplassen i sine egne registre.

Fløten i et nøtteskall

  1. En selskapsadministrator oppretter et API-element i Skava: et skjema pluss adressen til din backend, metode og token.
  2. Noen i chatten fyller ut skjemaet og sender det.
  3. Skava kaller backenden din og sender de utfylte verdiene som JSON.
  4. Svaret ditt blir kortet i chatten.
  5. Valgfritt rapporterer du nye tilstander senere via tilbakesendingen. Hver rapport blir et nytt kort, mens det forrige forblir.

Krav til backenden din

  • HTTPS. Kun https://, ingen http, ingen påloggingsopplysninger i adressen, maksimalt 2000 tegn.
  • Offentlig tilgjengelig. Verten må kun løses til offentlige IP-adresser. Localhost, private nettverk, link-local og sky-metadata avvises, og dette sjekkes ved hvert kall.
  • Fast adresse. Skava løser verten én gang og låser tilkoblingen til den IP-adressen. En DNS-endring underveis har ingen effekt.
  • Ingen omdirigeringer. En 301 til den «riktige» adressen teller som et feilslag. Oppgi den endelige adressen med en gang.
  • Svartid. Tidsavbruddet kan konfigureres per element og er hardt begrenset til 30 sekunder. Hvis du trenger lengre tid, svar umiddelbart og rapporter resultatet senere via tilbakemeldingen.
  • Svarstørrelse. Skava leser maksimalt 256 KiB.
  • Content-Type. Kroppen tolkes bare med application/json.

Forespørselen som når deg

Metoden er GET, POST, PUT eller PATCH, avhengig av elementet. Med POST, PUT og PATCH mottas verdiene som en JSON-kropp, mens de med GET sendes som spørringsparametere.

Autentisering er en header der navn og verdiprefiks er konfigurert i elementet, vanligvis Authorization med prefikset Bearer . Tokenet lagres kryptert hos oss. Headerne host, content-length, content-type, cookie og accept-encoding kan ikke settes.

Kroppen er et flatt objekt. Nøklene velges av den som bygget elementet; inngrep vises bare der de la til en tabell eller en produktvelger:

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

Tre nøkler kommer alltid fra oss, så bruk dem ikke selv:

  • locale: brukerens språkkode. Svar på det språket; vi oversetter ikke tekstene dine.
  • callback_url og callback_token: tilbakesendingen for denne interaksjonen, se nedenfor. De finnes bare når oppropet kommer fra en chat.

Kontekstfelt som navn, selskap, prosjekt eller subchat fylles av serveren selv, utledet fra kanalen elementet ble kjørt i. En manipulert klient kan ikke påstå et annet prosjektnavn der.

Svaret: kortformatet

Svar med 2xx og et card-objekt. Det er akkurat det som blir kortet i chatten:

{"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 (obligatorisk): heltallet 1. Som tekst ("1") forkastes det. Uten dette teller ikke svaret som et kort, og responsmappingen som er konfigurert i elementet gjelder.
  • title: kortets overskrift.
  • state: kun farge og ikonfarge, ett av ok, pending, warn, error. En ukjent verdi faller tilbake til ok, og du får en hint.
  • status_text: fri tekst som vi ikke tolker. Den står øverst på kortet og vises også i chattelisten og i pushvarsler.
  • fields: en liste med label og value. Maks 20 poster, label 80 tegn, value 200, title og status_text 120 hver. Verdier som er for lange blir kortet, ikke avvist: en ordre skal ikke feile på grunn av en detalj.
  • icon: se nedenfor.

Det Skava gjør med tekstene dine før de når chatten: linjeskift og kontrolltegn fjernes (et høyre-til-venstre-tegn kunne ellers snu visningen av et beløp), backticks erstattes, og alt som starter med [SKAVA: blir deaktivert. Sistnevnte hindrer at en kortverdi leses som et annet chattelement, for eksempel en betalingsforespørsel.

Lenker i felt, HTML og bilder kan ikke settes. En chat er et tillitetsmiljø, og en klikkbar adresse fra et eksternt backend-system ville være en invitasjon til å bygge en påloggingsside på nytt.

Brukerens inndata tilhører serveren: de vises på det første kortet og kan ikke overskrives. I chatten er de en registrering av det som faktisk ble sendt inn.

Ikoner

Med icon får kortet sitt eget merke i overskriften. To måter:

Ett navn fra den medfølgende samlingen: 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.

Eller ditt eget SVG som en streng. Skava tar kun geometrien fra denne (path, circle, ellipse, rect, line, polyline, polygon med deres numeriske attributter) og bygger sitt eget bilde. Skript, stiler, eksterne referanser, foreignObject og hendelsesattributter forkastes; en doctype eller en enhet fører til avvisning; filen kan være opptil 8 KiB og inneholde opptil 16 former. Farge, strekkbredde og størrelse settes av Skava, så et ikon kan ikke utgi seg for å være en kontroll. Bruk et rutenett på 24 x 24.

Uten icon forblir standardmerket.

Tilbakesending: rapportering av senere tilstander

Kallet inneholder callback_url og callback_token. Bruk dem for å rapportere nye tilstander senere:

POST <callback_url> med Authorization: Bearer <callback_token> og Content-Type: application/json, kropp på maksimalt 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}

I tillegg til kortet finnes det tre valgfrie verdier:

  • seq: din egen teller. En rapport med en lavere eller lik verdi forkastes, slik at to rapporter ikke kan overhale hverandre. Uten seq vinner den siste som mottas.
  • final: avslutter interaksjonen. Tokenet blir ugyldig og ingen flere kort vises. Tillatt også i det første svaret, for fløyer uten oppfølging.
  • notify: sett til false for å poste kortet stille, uten antall ulest og uten varsel. For mellomsteg som ikke skal vekke noen. Uten dette er kortet en helt vanlig melding.

Hver rapport blir sitt eget kort i chatten, og det forrige forblir. Dermed er det lesbart hvilken tilstand som ble rapportert. Derav følger en anbefaling: send bare det som endret seg. Et kort som gjentar ordrenummer, artikler og totalbeløp for fjerde gang er bare støy for leseren.

To grenser: samme rapport to ganger gir ikke et annet kort, og en interaksjon kan poste maks 50 kort. En interaksjon aksepterer rapporter i 90 dager.

Svar du bør reagere på

  • 200 med {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Les hintene: de forteller hva som ble forkortet eller droppet.
  • 401: feil token eller interaksjons-ID. Ikke prøv igjen.
  • 410: interaksjonen er lukket eller utløpt. Ikke prøv igjen.
  • 422: kortet er ubrukbart, med hints som årsak. Rett det først.
  • 400 feil i JSON, 413 for stor, 429 for mange forespørsler (prøv igjen med tilbakefall), 500 feil på vår side, prøv igjen senere.

Eksempel 1: en ordre med statushistorikk

Steg 1, forespørselen til din 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"}

Steg 2, ditt umiddelbare svar:

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

Chatten viser nå et kort med en pakkeikon, statusen og brukerens inndata.

Steg 3, senere under valg:

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

En stille andre kort uten felt: bare statusen endret seg.

Steg 4, ved frakt:

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}

Dette kortet kan gjerne vekke noen, derfor ingen notify: false.

Steg 5, ved levering:

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

Med final er interaksjonen avsluttet og tokenet fungerer ikke lenger.

Eksempel 2: en handling uten oppfølging

Ikke alle flater har en historikk. Et element med ett felt som sender noe til systemet ditt, krever bare ett svar:

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

final: true er viktig her: ellers ville interaksjonen blitt åpen i 90 dager med et gyldig token, selv om du aldri rapporterer noe mer.

Produktvelger fra katalogen

Når selskapet har lastet opp varekatalogen, kan elementet inneholde blokken varevelger. Brukeren lager en handlekurv fra denne, og du mottar den som en liste under nøkkelen som ble valgt av den som bygde elementet:

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

Siden nøkkelen er fri, søk etter den første listen som har denne strukturen i stedet for et fast navn. Før sending sjekker Skava at alle tall faktisk finnes i selskapets katalog, med maksimalt 50 varer. I kortet vises varene som en liste med bilde, navn og antall.

Testing

  • Ping i elementredigeringen sender en ren HEAD uten token og uten data. Svar med hva som helst. Ethvert HTTP-svar teller som tilgjengelig.
  • Testforespørsel utløser et ekte kall med eksempelverdier, selv når elementet fortsatt er utkast, og viser forespørselen, responsen og meldingene fra kortvalidereren.
  • Forhåndsvisning i fanen ved siden av: lim inn respons-JSON-en, sjekk, og du ser ferdig kortet pluss hintene. Det sjekkes på serveren med samme kode som i produksjon.
  • Eksempelserver: en komplett eksempelleverandør kjører på api.skava.io og bruker alt som er beskrevet ovenfor. Kilden ligger i repositoret under example_order_server/, omtrent 600 linjer med ren standardbibliotek, ment å bli kopiert.

Hva du ellers bør vite

  • Kortet er en fullt vanlig chatmelding. Den vises i søket, kan siteres og ligger i historikken.
  • Den sendes av systemavsenderen, ikke av en konto hos ditt selskap. Den vises fortsatt på siden til den som kjørte elementet, og hvem som skriver står i tittelen.
  • Hvem som kan kjøre det, er satt på elementet: bare medlemmer av selskapet, eller også eksterne som deler en chat med det. Når selskapet ditt forlater chatten, opphører tillatelsen automatisk.
  • Et API-element med utløpt token er inaktiv: gjeldende apper skjuler det i menyen, og et kall som likevel sendes, forkastes på tjeneren. En administrator lagrer et nytt token for det, noe som også fungerer på et frigitt grensesnitt.

Relatert

Oppretting og frigivning: Custom Elements: API-grensesnitt. Utfylbare dokumenter i stedet for grensesnitt: Custom Elements: Dokumenter.