Skava Skava / Wiki

Forbindelse af tilpassede elementer for udviklere

Denne side er til udviklere, der kobler et firmas backend til Skava. Oprettelse og frigivelse af et API-element behandles på Tilpassede elementer: API-grænseflader; her dækker vi alt, der skal ske på den anden ende af linjen.

Ideer i én sætning: Skava kender ikke dit domæne. Den kender præcis ét format, kortet. Du bestemmer, hvad det siger, vi tjekker kun form, størrelse og sikkerhed. En materialebestilling er et eksempel; det næste firma indsamler brugerfeedback, det efterfølgende arkiverer et sitefoto i sine egne optegnelser.

Flowet i et overblik

  1. En firmaadministrator opretter et API-element i Skava: et formular plus din backends adresse, metode og token.
  2. En person 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 rapporterer du nye tilstande senere via callback. Hver rapport bliver til et nyt kort, mens det forrige forbliver.

Krav til din backend

  • HTTPS. Kun https://, ingen http, ingen adgangsdetaljer i adressen, maksimalt 2000 tegn.
  • Offentligt tilgængelig. Værten skal kun opløses til offentlige IP-adresser. Localhost, private netværk, link-local og cloud-metadata afvises, og dette tjekkes ved hver opkald.
  • Fast adresse. Skava opløser værten én gang og låser forbindelsen til den IP. En DNS-ændring undervejs har ingen effekt.
  • Ingen omdirigeringer. En 301 til den "korrekte" adresse tæller som et fejl. Indtast den endelige adresse med det samme.
  • Svartid. Timeout kan konfigureres pr. element og er hårdt begrænset til 30 sekunder. Hvis du behøver 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. Brønden tolkes kun med application/json.

Anmodningen, der når frem til dig

Metoden er GET, POST, PUT eller PATCH, afhængigt af elementet. Ved POST, PUT og PATCH ankommer værdierne som en JSON-brød, mens de ved GET ankommer som query-parametre.

Autentificering er en header, hvis navn og værdipræfix konfigureres i elementet, normalt Authorization med præfikset Bearer . Tokenet opbevares krypteret på vores side. Headerne host, content-length, content-type, cookie og accept-encoding kan ikke sættes.

Kroppen er et fladt objekt. Nøglerne vælges af den, der har bygget elementet; indrykning opstår 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 som navn, virksomhed, projekt eller subchat udfyldes af serveren selv, udledt fra den kanal, elementet blev kørt i. En manipuleret klient kan ikke påstå 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 (obligatorisk): 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 ikonets tone, én af ok, pending, warn, error. En ukendt værdi falder tilbage til ok, og du får en hint.
  • status_text: fritext, som vi ikke fortolker. Den sidder øverst på kortet og vises også i chatlisten og i pushnotifikationer.
  • fields: en liste over label og value. Højst 20 poster, label 80 tegn, value 200, title og status_text 120 hver. Værdier, der er for lange, bliver forkortet, ikke afvist: en ordre skal ikke fejle på grund af en detalje.
  • icon: se nedenfor.

Det Skava gør med dine tekster, før de når frem til 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. Det sidste forhindrer, at en kortværdi læses som et andet chat-element, for eksempel en betalingsanmodning.

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

Brugernes input tilhører serveren: de vises på det første kort og kan ikke overskrives. I chatten er de optegnelsen af, hvad der faktisk blev indsendt.

Ikoner

Med icon får kortet sit eget mærke i headeren. To måder:

Et navn fra den 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. Fra det tager Skava kun geometrien (path, circle, ellipse, rect, line, polyline, polygon med deres numeriske attributter) og bygger sit eget billede. Skripter, stilarter, eksterne referencer, foreignObject og hændelsesattributter forkastes; en doctype eller en enhed medfører afvisning; filen må højst være 8 KiB og indeholde højst 16 former. Farve, strelletykkelse og størrelse sættes af Skava, så et ikon ikke kan forklæde sig som en kontrol. Arbejd med et 24 x 24 gitter.

Uden icon forbliver det standardmærke.

Callback: Rapportering af senere tilstande

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

Ud over kortet er der tre valgfrie værdier:

  • seq: din egen tæller. En rapport med en lavere eller ligeværdig værdi forkastes, så to rapporter ikke kan overhale hinanden. Uden seq vinder den, der ankommer sidst.
  • final: afslutter interaktionen. Tokenet bliver ugyldigt, og der vises ingen flere kort. Tilladt også 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 notifikation. Til mellemstadier, der ikke skal vække nogen. Uden det er kortet en helt almindelig besked.

Hver rapport bliver sit eget kort i chatten, og det forrige forbliver. Det gør det læsbart, hvilken tilstand der blev rapporteret. Deraf følger en anbefaling: send kun det, der ændrede sig. Et kort, der gentager ordrenummer, varer og total for fjerde gang, er bare støj for læseren.

To grænser: den samme rapport to gange giver ikke et andet kort, og en interaktion kan poste højst 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 hints: de angiver, hvad der er forkortet eller droppet.
  • 401: forkert token eller interaction id. Prøv ikke igen.
  • 410: interaction lukket eller udløbet. Prøv ikke igen.
  • 422: kortet kan ikke bruges, med hints som årsag. Ret det først.
  • 400 beskadiget JSON, 413 for stor, 429 for mange anmodninger (prøv igen med back-off), 500 vores fejl, prøv senere.

Eksempel 1: en ordre med statushistorik

Trin 1, anmodningen til dit 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 en pakkeikon, status og brugerens input.

Trin 3, senere under udvælgelse:

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 anden kort uden felter: kun statusen æ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 sagtens 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 lukket, og tokenet virker ikke længere.

Eksempel 2: en handling uden opfølgning

Ikke alle flows har en historik. Et element med et enkelt felt, der sender 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 vigtigt her: ellers ville interaktionen være åben i 90 dage med et gyldigt token, selvom du aldrig rapporterer noget mere.

Produktvælger fra kataloget

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

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

Da nøglen er fri, skal du lede efter den første liste, der har denne struktur, i stedet for et fast navn. Før afsendelse kontrollerer Skava, at alle tal faktisk findes i virksomhedens katalog, med maksimalt 50 varer. I kortet vises varerne som en liste med produktbillede, navn og antal.

Test

  • Ping i elementredigeringen sender en ren HEAD uden token og uden data. Svar med hvad som helst, da ethvert HTTP-svar tæller som tilgængeligt.
  • Testanmodning udløser et rigtigt kald med eksempelværdier, selv mens elementet stadig er et udkast, og viser anmodningen, responsen og kortvalideringens beskeder.
  • Forhåndsvisning i fanen ved siden af: indsæt dit svar-JSON, tjek, og du ser den færdige kort samt hintene. Det tjekkes på serveren med samme kode som i produktion.
  • Eksempelserver: en komplet eksempeludbyder kører på api.skava.io og bruger alt det, der er beskrevet ovenfor. Kilden ligger i repository 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 bliver liggende i historikken.
  • Den sendes af systemets afsender, ikke af en konto hos dit firma. Den vises stadig på siden af den, der kørte elementet, og hvem der skriver, står i titlen.
  • Hvem der må køre det, er indstillet på elementet: kun medlemmer af virksomheden, eller også eksterne, der deler en chat med det. Når jeres virksomhed forlader chatten, ophører tilladelsen automatisk.
  • Et API-element med en udløbet token er inaktiv: aktuelle apps skjuler det i menuen, og et kald, der sendes alligevel, afvises server-side. En admin gemmer en ny token til det, hvilket også virker på et frigivet interface.

Relateret

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