Denne siden er for utviklere som kobler et selskaps backend til Skava. Hvordan et API-element opprettes og utgis, er beskrevet på Custom Elements: API-grensesnitt; her dekker vi alt som må skje på den andre enden av linjen.

Idéen på én setning: Skava kjenner ikke din domene. Den kjenner nøyaktig ett format, kortet. Du bestemmer hva det sier, vi sjekker bare form, størrelse og sikkerhet. En materialebestilling er ett eksempel; neste selskap samler brukerfeedback, det etter det lagrer et bilde av byggeplassen i sine egne registre.

Fløten i et glimt

1. En selskapsadministrator oppretter et API-element i Skava: et skjema pluss din backends adresse, metode og token.
2. Noen i chatten fyller ut skjemaet og sender det.
3. Skava kaller på din backend og sender de utfylte verdiene som JSON.
4. Ditt svar blir til kortet i chatten.
5. Valgfritt kan du senere rapportere nye tilstander gjennom tilbakekallingen. Hver rapport blir til et nytt kort; det forrige forblir.

Krav til din backend

• 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 forkastes, og dette sjekkes ved hvert kall.
• Fast adresse. Skava løser verten én gang og låser forbindelsen til den IP-adressen. En DNS-endring midt i et kall har ingen effekt.
• Ingen omdirigeringer. En 301-omdirigering til den «riktige» adressen regnes som feil. Oppgi den endelige adressen med en gang.
• Svar tid. Tidsavbruddet er konfigurerbart per element og har en hard grense på 30 sekunder. Hvis du trenger lengre tid, svar umiddelbart og rapporter resultatet senere gjennom tilbakekallet.
• Svarstørrelse. Skava leser maksimalt 256 KiB.
• Content-Type. Kroppen blir bare analysert med application/json.

Forespørselen du mottar

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

Autentisering er ett hodefelt hvis navn og verdiprefiks er konfigurert i elementet, vanligvis Authorization med prefikset Bearer . Tokenet lagres kryptert på vår side. Hodefeltene 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; innsnevring opptrer 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 dine tekster.
• callback_url og callback_token: tilbakekallingen for denne interaksjonen, se nedenfor. De er bare til stede når oppkallet kommer fra en chat.

Kontekstfelter som navn, selskap, prosjekt eller underchat fylles av serveren selv, utledet fra kanalen elementet ble kjørt i. Et manipulert klientprogram kan ikke hevde et annet prosjektnavn der.

Svaret: kortformatet

Svar med 2xx og et card-objekt. Det er nøyaktig 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 (pålagt): heltallet 1. Som tekst ("1") blir det forkastet. Uten det regnes svaret ikke som et kort, og responsmappingen som er konfigurert i elementet, gjelder.
• title: kortets overskrift.
• state: bare 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 vises øverst på kortet og er også det som vises i chatlisten og i en push-notifikasjon.
• fields: en liste med label og value. Maksimalt 20 oppføringer, label 80 tegn, value 200, title og status_text 120 hver. Verdier som er for lange blir forkortet, ikke avvist: en bestilling skal ikke feile på grunn av en detalj.
• icon: se nedenfor.

Hva 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 nøytralisert. Det siste forhindrer at en kortverdi leses som et annet chat-element, for eksempel en betalingsforespørsel.

Lenker i felt, HTML og bilder kan ikke settes. En chat er et tillitsfullt miljø, og en klikkbart adresse fra en fremmed backend ville være en invitasjon til å bygge opp en innloggingsside på nytt.

Brukerens inputs tilhører serveren: de vises på det første kortet, og du kan ikke overskrive dem. I chatten er de dokumentasjonen av hva som faktisk ble sendt inn.

Ikoner

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

Et navn fra det inkluderte settet: 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 din egen SVG som en streng. Skava henter kun geometrien (path, circle, ellipse, rect, line, polyline, polygon med deres numeriske attributter) og bygger sitt eget bilde. Skript, stiler, eksterne referanser, foreignObject og hendelsesattributter blir forkastet; en doctype eller en entitet fører til avvisning; filen kan være på maksimalt 8 KiB og inneholde maksimalt 16 former. Farge, strekbredde og størrelse settes av Skava, så et ikon kan ikke utgi seg for å være en kontroll. Arbeid med et 24x24-rutenett.

Uten icon forblir standardmerket.

Tilbakekall: 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, kroppsinnhold 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 mindre eller lik verdi blir forkastet, slik to rapporter ikke kan overhente hverandre. Uten seq vinner den siste som ankommer.
• final: avslutter interaksjonen. Tokenet blir ugyldig og det vises ingen flere kort. Også tillatt i det first svaret for flyter uten oppfølgning.
• notify: sett til false for å poste kortet stille, uten antall uläste og uten varsling. For mellomtrinn som ikke skal vekke noen. Uten dette er kortet en helt vanlig melding.

Hver rapport blir sitt eget kort i chatten, den forrige forblir. På den måten er det tydelig hvilken tilstand som ble rapportert. Dermed følger en anbefaling: send bare det som har endret seg. Et kort som gjentar ordrenummer, poster og totalbeløp for fjerde gang er bare støy for leseren.

To begrensninger: samme rapport to ganger gir ikke et nytt kort, og en interaksjon kan poste maksimalt 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 er forkortet eller droppet.
• 401: feil token eller interaksjons-ID. Prøv ikke igjen.
• 410: interaksjon lukket eller utløpt. Prøv ikke igjen.
• 422: kort kan ikke brukes, med hints som årsak. Løs det først.
• 400 ødelagt JSON, 413 for stort, 429 for mange forespørsler (prøv igjen med avstand), 500 vår feil, prøv senere.

Eksempel 1: en ordre med statushistorikk

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

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

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

Trinn 3, senere under plukking:

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

Et rolig andre kort uten felt: bare statusen endret seg.

Steg 4, ved forsendelse:

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 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ølgning

Ikke alle flyt har en historikk. Et element med ett felt som overleverer noe til systemet ditt trenger 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 forblitt åpen i 90 dager med en gyldig token, selv om du aldri vil rapportere noe igjen.

Produktvelger fra katalogen

Når selskapet har lastet opp sin artikkelkatalog, kan elementet inneholde blokken produktvelger. Brukeren setter sammen en handlekurv fra den, og du mottar den som en liste under nøkkelen valgt av den som bygget elementet:

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

Siden nøkkelen er fri, se etter den første listen som har denne formen i stedet for et fast navn. Før sending sjekker Skava at hvert nummer faktisk finnes i selskapets katalog, maksimalt 50 elementer. I kortet vises elementene som en liste med produktbilde, navn og mengde.

Testing

• Ping i elementredigereren sender en ren HEAD uten token og uten data. Svar med hva som helst; ethvert HTTP-svar regnes som tilgjengelig.
• Test forespørsel utløser et ekte kall med eksempelverdier, selv mens elementet fortsatt er utkast, og viser forespørselen, svaret og kortvalidererens meldinger.
• Forhåndsvisning i fanen ved siden av: lim inn responsen din som JSON, sjekk, og du ser det ferdige 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 over. Kilden ligger i repositoryet under example_order_server/, omtrent 600 linjer med ren standardbibliotek, ment å bli kopiert.

Hva du ellers bør vite

• Kortet er en helt vanlig chatmelding. Den vises i søk, kan siteres og blir liggende i historikken.
• Den sendes av systemavsenderen, ikke av en konto i ditt selskap. Den vises likevel på siden til den som kjørte elementet, og hvilket system som skriver står oppgitt i tittelen.
• Hvem som kan kjøre det, er satt på elementet: kun medlemmer av selskapet, eller også utenforstående som deler en chat med det. Når ditt selskap forlater chatten, opphører tillatelsen automatisk.
• Et API-element med utløpt token er inaktivt og vises ikke i menyen før en administrator lagrer et nytt.

Relatert

Opprette og publisere: Custom Elements: API-grensesnitt. Fyltbare dokumenter i stedet for grensesnitt: Custom Elements: Dokumenter.