Denne side er for udviklere, der forbinder en virksomheds backend med Skava. Hvordan et API-element oprettes og udgives, beskrives på Custom Elements: API-grænseflader; her dækker vi alt, der skal ske på den anden ende af linjen.

Idéen på én sætning: Skava kender ikke dit domæne. Det kender præcis én format, kortet. Du bestemmer, hvad det siger, vi tjekker kun form, størrelse og sikkerhed. En materialebestilling er ét eksempel; den næste virksomhed indsamler brugerfeedback, og den efterfølgende arkiverer et foto fra byggepladsen i sine egne registre.

Flowet på et overblik

1. En virksomhedsadministrator opretter et API-element i Skava: et formular plus din backends adresse, metode og token.
2. Nogen i chatten udfylder formularen og sender den.
3. Skava kalder din backend og sender de udfyldte værdier som JSON.
4. Dit svar bliver til kortet i chatten.
5. Valgfrit kan du senere rapportere nye tilstande via callback. Hver rapport bliver til et nyt kort, mens det tidligere forbliver.

Krav til din backend

• HTTPS. Kun https://, ingen http, ingen loginoplysninger i adressen, maksimalt 2000 tegn.
• Offentligt tilgængelig. Værten må kun løses til offentlige IP-adresser. Localhost, private netværk, link-local og cloud metadata afvises, og dette tjekkes ved hvert opkald.
• Fast adresse. Skava løser værten én gang og fastgør forbindelsen til den IP. En DNS-ændring midt i opkaldet har ingen effekt.
• Ingen omdirigeringer. En 301 til den "korrekte" adresse tæller som et fejlslag. Indtast den endelige adresse med det samme.
• Svarhastighed. Timeouten kan konfigureres pr. element og er hårdt begrænset til 30 sekunder. Hvis du har brug for længere tid, svar med det samme og rapportér resultatet senere via callback.
• Svarstørrelse. Skava læser højst 256 KiB.
• Content-Type. Kroppen bliver kun fortolket med application/json.

Anmodningen, der når dig

Metoden er GET, POST, PUT eller PATCH, afhængigt af elementet. Ved POST, PUT og PATCH ankommer værdierne som en JSON-krop, mens de ved GET ankommer som forespørgselsparametre.

Autentificering er én header, hvis navn og værdipræfiks er konfigureret i elementet, normalt Authorization med præfikset Bearer . Tokenet er krypteret og gemt på vores side. Hovederne host, content-length, content-type, cookie og accept-encoding kan ikke indstilles.

Kroppen er et fladt objekt. Nøglerne vælges af den, der har bygget elementet. Indlejring optræder kun, hvor de har tilføjet en tabel eller en produktvælger:

{"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øgler kommer altid fra os, så brug dem ikke selv:

• locale: brugerens sprogkode. Svar på det sprog; vi oversætter ikke dine tekster.
• callback_url og callback_token: callback for denne ene interaktion, se nedenfor. De er kun til stede, når opkaldet kommer fra en chat.

Kontekstfelter såsom name, company, project eller subchat udfyldes af serveren selv, udledt fra kanalen, elementet blev kørt i. Et manipuleret klientprogram kan ikke hævde et andet projekt navn der.

Svaret: kortformatet

Svar med 2xx og et card-objekt. Det er præcis det, der bliver til 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åkrævet): heltallet 1. Som tekst ("1") afvises det. Uden det tæller svaret ikke som et kort, og det svarmapping, der er konfigureret i elementet, gælder.
• title: kortets overskrift.
• state: kun farve og ikontone, en af ok, pending, warn, error. En ukendt værdi falder tilbage til ok, og du får en hint.
• status_text: fritekst, som vi ikke fortolker. Den sidder øverst på kortet og er også det, der vises i chatlisten og i en push-notifikation.
• fields: en liste over label og value. Højst 20 indgange, label 80 tegn, value 200, title og status_text 120 hver. Værdier, der er for lange, bliver forkortet, ikke afvist: en ordre må ikke fejle på grund af en detalje.
• icon: se nedenfor.

Det Skava gør ved dine tekster, før de når chatten: linjeskift og kontroltegn fjernes (et højre-til-venstre-tegn kunne ellers vende visningen af et beløb), backticks erstattes, og alt, der starter med [SKAVA:, neutraliseres. Sidstnævnte forhindrer, at en kortværdi læses som et andet chatelement, for eksempel en betalingsanmodning.

Links i felter, HTML og billeder kan ikke indstilles. En chat er et tillidsbaseret miljø, og en klikbar adresse fra en fremmed backend ville være en invitation til at genopbygge en login-side.

Brugerens inputs tilhører serveren: de vises på det første kort, og du kan ikke overskrive dem. I chatten er de optegnelsen af, hvad der faktisk blev indsendt.

Ikoner

Med icon får kortet sit eget symbol i overskriften. To måder:

Et navn fra det medfølgende sæt: 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 dit eget SVG som en streng. Skava henter kun geometrien (path, circle, ellipse, rect, line, polyline, polygon med deres numeriske attributter) og bygger sit eget billede. Scripts, styles, eksterne referencer, foreignObject og hændelsesattributter kasseres; en doctype eller en enhed fører til afvisning; filen må højst være 8 KiB og indeholde højst 16 former. Farve, stregbredde og størrelse sættes af Skava, så et ikon kan ikke udgive sig for at være en kontrol. Arbejd med et 24 x 24 gitter.

Uden icon forbliver standardtegnet.

Tilbagekaldelsen: rapportering af senere tilstande

Opringningen indeholder callback_url og callback_token. Brug dem til at rapportere nye tilstande senere:

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

Udover kortet er der tre valgfrie værdier:

• seq: din egen tæller. En rapport med en mindre eller ligeværdig værdi kasseres, så to rapporter ikke kan overhale hinanden. Uden seq vinder den sidste, der ankommer.
• final: afslutter interaktionen. Tokenet bliver ugyldigt, og der vises ikke flere kort. Det er også tilladt i det første svar til flows uden opfølgning.
• notify: sæt til false for at poste kortet stille, uden ulæst tæller og uden notifikation. Til mellemtrin, der ikke skal vække nogen. Uden det er kortet en helt almindelig besked.

Hver rapport bliver sit eget kort i chatten, og den forrige forbliver. På den måde kan man se, hvilken status der blev rapporteret. Det medfører en anbefaling: send kun det, der er ændret. Et kort, der gentager ordrenummer, poster og total for fjerde gang, er bare støj for læseren.

To begrænsninger: den samme rapport to gange giver ikke et andet kort, og en interaktion kan højst poste 50 kort. En interaktion accepterer rapporter i 90 dage.

Svar, du skal reagere på

• 200 med {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Læs hintene: de fortæller, hvad der er forkortet eller udeladt.
• 401: forkert token eller interaktions-id. Prøv ikke igen.
• 410: interaktion lukket eller udløbet. Prøv ikke igen.
• 422: kort kan ikke bruges, med hints som årsag. Ret det først.
• 400 defekt JSON, 413 for stort, 429 for mange anmodninger (prøv igen med back-off), 500 vores fejl, prøv senere igen.

Eksempel 1: en ordre med statushistorik

Trin 1, anmodningen 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"}

Trin 2, dit øjeblikkelige 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 nu et kort med et pakkeikon, status og brugerens input.

Trin 3, senere under pakkning:

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 stille sekundært kort uden felter: kun status ændrede sig.

Trin 4, ved afsendelse:

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 kort kan godt vække nogen, derfor ingen notify: false.

Trin 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 interaktionen afsluttet, og tokenet virker ikke længere.

Eksempel 2: en handling uden opfølgning

Ikke hver flow har en historik. Et element med et enkelt felt, der overdrager noget til dit system, kræver kun ét 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 afgørende her: ellers ville interaktionen forblive åben i 90 dage med en gyldig token, selvom du aldrig vil rapportere noget igen.

Produktvælger fra kataloget

Når virksomheden har uploadet sit artikelkatalog, kan elementet indeholde produktvælger-blokken. Brugeren samler en kurv fra den, og du modtager den som en liste under nøglen valgt af den, der byggede elementet:

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

Da nøglen er fri, skal du lede efter den første liste med denne struktur i stedet for et fast navn. Før afsendelse tjekker Skava, at hvert nummer faktisk findes i virksomhedens katalog, højst 50 varer. I kortet vises varerne som en liste med produktbillede, navn og mængde.

Testning

• Ping i elementredigereren sender en ren HEAD-forespørgsel uden token og uden data. Svar med hvad som helst; ethvert HTTP-svar tæller som tilgængeligt.
• Test forespørgsel udfører et rigtigt kald med prøveværdier, selv mens elementet stadig er udkast, og viser forespørgslen, svaret og kortvalideringens beskeder.
• Forhåndsvisning i fanen ved siden af: indsæt dit svar i JSON-format, tjek, og du ser det færdige kort samt henvisningerne. Det tjekkes på serveren med samme kode som i produktion.
• Eksempelserver: en komplet eksempeludbyder kører på api.skava.io og bruger alt, der er beskrevet ovenfor. Kilden findes i lageret under example_order_server/, cirka 600 linjer ren standardbibliotek, beregnet til at blive kopieret.

Hvad du ellers bør vide

• Kortet er en helt almindelig chatbesked. Den vises i søgning, kan citeres og forbliver i historikken.
• Den sendes af systemets afsender, ikke af en konto i dit firma. Den vises stadig på siden af den, der har kørt elementet, og hvis system der skriver, er angivet i titlen.
• Hvem der må køre det, er indstillet på elementet: kun medlemmer af firmaet, eller også udefrakommende, der deler en chat med det. Når dit firma forlader chatten, ophører tilladelsen automatisk.
• Et API-element med en udløbet token er inaktivt og vises ikke engang i menuen, før en administrator gemmer en ny.

Relateret

Oprettelse og frigivelse: Custom Elements: API-grænseflader. Udfyldelige dokumenter i stedet for grænseflader: Custom Elements: Dokumenter.