Skava Skava / Wiki

Ansluta anpassade element för utvecklare

Denna sida är för utvecklare som ansluter ett företags backend till Skava. Hur ett API-element skapas och publiceras beskrivs på Anpassade element: API-gränssnitt. Här behandlar vi allt som måste ske på andra sidan linjen.

Idén på en mening: Skava känner inte till din domän. Den känner till exakt ett format, nämligen kortet. Du bestämmer vad det innehåller, vi kontrollerar bara form, storlek och säkerhet. En materialbeställning är ett exempel. Nästa företag samlar in användarfeedback, det nästföljande arkiverar en platsbild i sina egna register.

Flödet i korthet

  1. En företagsadministratör skapar ett API-element i Skava: ett formulär samt din backends adress, metod och token.
  2. Någon i chatten fyller i formuläret och skickar det.
  3. Skava anropar din backend och skickar de ifyllda värdena som JSON.
  4. Ditt svar blir kortet i chatten.
  5. Valfritt rapporterar du nya stater senare via callback. Varje rapport blir ett nytt kort; det tidigare förblir.

Krav på din backend

  • HTTPS. Endast https://, ingen http, inga inloggningsuppgifter i adressen, högst 2000 tecken.
  • Publikt tillgänglig. Värdnamnet måste lösa till enbart publika IP-adresser. Localhost, privata nätverk, link-local och molnmetadata avvisas, och detta kontrolleras vid varje anrop.
  • Fast adress. Skava löser värdnamnet en gång och låser anslutningen till den IP-adressen. En DNS-ändring under pågående anrop har ingen effekt.
  • Inga omdirigeringar. En 301 till den "korrekta" adressen räknas som ett misslyckande. Ange den slutgiltiga adressen direkt.
  • Svarstid. Tidsgränsen är konfigurerbar per element och har en övre gräns på 30 sekunder. Om du behöver längre tid, svara omedelbart och rapportera resultatet senare via callback.
  • Svarstorlek. Skava läser högst 256 KiB.
  • Content-Type. Brödtexten tolkas endast med application/json.

Begäran som når dig

Metoden är GET, POST, PUT eller PATCH, beroende på elementet. Med POST, PUT och PATCH kommer värdena som en JSON-brödtext, medan de med GET kommer som frågeparametrar.

Autentiseringen är en header vars namn och värdeprefix konfigureras i elementet, oftast Authorization med prefixet Bearer . Token lagras krypterat på vår sida. Headrarna host, content-length, content-type, cookie och accept-encoding kan inte sättas.

Kroppen är ett platt objekt. Nycklarna väljs av den som byggde elementet; nästning visas endast där de lade till en tabell eller en produktväljare:

{"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 nycklar kommer alltid från oss, så använd dem inte själv:

  • locale: användarens språkkod. Svara på det språket; vi översätter inte dina texter.
  • callback_url och callback_token: callback för denna interaktion, se nedan. De finns endast när anropet kommer från en chatt.

Sammanhangsfält som namn, företag, projekt eller subchatt fylls i av servern själv, härledda från kanalen där elementet kördes. En manipulerad klient kan inte hävda ett annat projektnamn där.

Svaret: kortformatet

Svara med 2xx och ett card-objekt. Det är exakt 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 (obligatoriskt): heltalsvärdet 1. Som text ("1") avvisas det. Utan det räknas svaret inte som ett kort och mappningen för svaret som konfigurerats i elementet tillämpas.
  • title: kortets rubrik.
  • state: endast färg och ikonens ton, ett av ok, pending, warn, error. Ett okänt värde faller tillbaka på ok och du får en hint.
  • status_text: fritt text som vi inte tolkar. Den visas överst på kortet och syns även i chattlistan och i pushaviseringar.
  • fields: en lista med label och value. Max 20 poster, label 80 tecken, value 200, title och status_text 120 vardera. För långa värden klippas, inte avvisas: en order ska inte misslyckas på grund av en detalj.
  • icon: se nedan.

Det Skava gör med dina texter innan de når chatten: radbrytningar och styrtecken tas bort (ett höger till vänster-tecken kunde annars vända visningen av ett belopp), bakgrindstreck ersätts och allt som börjar med [SKAVA: neutraliseras. Det sista förhindrar att ett kortvärde tolkas som ett annat chattobjekt, till exempel en betalningsbegäran.

Länkar i fält, HTML och bilder kan inte anges. En chatt är en betrodd miljö, och en klickbar adress från ett utomstående backend skulle vara en inbjudan att bygga om en inloggningssida.

Användarens inmatningar tillhör servern: de visas på det första kortet och kan inte skrivas över. I chatten är de en logg över vad som faktiskt skickades in.

Ikoner

Med icon får kortet en egen markering i sidhuvudet. Två sätt:

Ett namn från den medföljande uppsättningen: 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 sträng. Från den tar Skava bara geometrin (path, circle, ellipse, rect, line, polyline, polygon med deras numeriska attribut) och bygger sin egen bild. Skript, stilar, externa referenser, foreignObject och händelseattribut kastas bort; en doctype eller en entitet leder till avvisning; filen får vara högst 8 KiB och innehålla högst 16 former. Färg, streckbredd och storlek sätts av Skava, så en ikon kan inte dölja sig som en kontroll. Arbeta med ett rutnät på 24 gånger 24.

Utan icon förblir standardmarkeringen.

Kallbacken: rapportering av senare tillstånd

Anropet innehåller callback_url och callback_token. Använd dem för att rapportera nya tillstånd senare:

POST <callback_url> med Authorization: Bearer <callback_token> och Content-Type: application/json, brödtext högst 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}

Utöver kortet finns tre valfria värden:

  • seq: din egen räknare. En rapport med ett lägre eller lika värde förkastas, så att två rapporter inte kan passera varandra. Utan seq gäller den sista som kommer in.
  • final: avslutar interaktionen. Tokenen blir ogiltig och inga fler kort visas. Tillåtet även i det första svaret, för flöden utan uppföljningar.
  • notify: sätt till false för att posta kortet tyst, utan oläst-räknare och utan notifikation. För mellansteg som inte ska väcka någon. Utan det är kortet ett helt vanligt meddelande.

Varje rapport blir sitt eget kort i chatten, det föregående förblir kvar. På så sätt går det att se vilken status som rapporterades. Därför gäller rekommendationen: skicka bara det som ändrats. Ett kort som upprepar ordernummer, artiklar och totalbelopp för fjärde gången är bara brus för mottagaren.

Två gränser: samma rapport två gånger ger inte ett andra kort, och en interaktion kan posta högst 50 kort. En interaktion accepterar rapporter i 90 dagar.

Svar du bör reagera på

  • 200 med {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Läs hinterna: de anger vad som förkortats eller tagits bort.
  • 401: fel token eller interaktions-id. Försök inte igen.
  • 410: interaktion stängd eller utgången. Försök inte igen.
  • 422: kortet är oanvändbart, med hints som anledning. Åtgärda det först.
  • 400 trasig JSON, 413 för stor, 429 för många anrop (försök igen med backoff), 500 vårt fel, försök senare.

Exempel 1: en order med statushistorik

Steg 1, anropet till 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 omedelbara 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 visar nu ett kort med en paketikon, statusen och användarens inmatning.

Steg 3, senare vid val:

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 tyst andra kort utan fält: endast statusen ändrades.

Steg 4, vid 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}

Detta kort kan väcka någon, därför inget notify: false.

Steg 5, vid leverans:

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 avslutas interaktionen och token fungerar inte längre.

Exempel 2: en åtgärd utan uppföljningar

Inte alla flöden har en historik. Ett element med ett fält som skickar något till ditt system behöver bara 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 är viktigt här: annars skulle interaktionen vara öppen i 90 dagar med en giltig token, även om du aldrig rapporterar något igen.

Produktväljare från katalogen

När företaget har laddat upp sin artikelkatalog kan elementet innehålla blocket produktväljare. Användaren sätter ihop en varukorg från den, och du får den som en lista under den nyckel som den som byggde elementet valt:

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

Eftersom nyckeln är fri, leta efter den första listan som har denna struktur istället för ett fast namn. Innan skickning kontrollerar Skava att varje nummer verkligen finns i företagets katalog, högst 50 artiklar. I kortet visas artiklarna som en lista med produktbild, namn och antal.

Testning

  • Ping i elementredigeraren skickar en ren HEAD utan token och utan data. Svara med vad som helst, varje HTTP-svar räknas som nåbar.
  • Testförfrågan gör ett riktigt anrop med exempelvärden, även medan elementet fortfarande är ett utkast, och visar förfrågan, svaret och kortvaliderarens meddelanden.
  • Översikt i fliken bredvid: klistra in ditt svar i JSON-format, kontrollera och du ser den färdiga kortet samt ledtrådarna. Det kontrolleras på servern med samma kod som i produktion.
  • Exempelservrar: en komplett exempelleverantör körs på api.skava.io och använder allt som beskrivits ovan. Källkoden finns i repot under example_order_server/, cirka 600 rader ren standardbibliotek, avsedd att kopieras.

Vad du bör veta mer

  • Kortet är ett helt vanligt chattmeddelande. Det visas i sökningen, kan citeras och finns kvar i historiken.
  • Det skickas av systemets avsändare, inte av ett konto hos ditt företag. Det visas fortfarande på sidan av den som körde elementet, och vilken system som skriver anges i titeln.
  • Vem som får köra det anges på elementet: endast medarbetare i företaget, eller även externa som delar en chatt med det. När ert företag lämnar chatten upphör behörigheten automatiskt.
  • Ett API-element med utgången token är inaktivt: aktuella appar döljer det i menyn, och ett anrop som ändå skickas avvisas på serversidan. En administratör sparar en ny token för det, vilket också fungerar på en publicerad gränssnitt.

Relaterat

Skapa och publicera: Custom Elements: API-gränssnitt. Fyllbara dokument istället för gränssnitt: Custom Elements: Dokument.