Deze pagina is voor ontwikkelaars die de backend van een bedrijf aan Skava koppelen. Hoe een API-element wordt aangemaakt en vrijgegeven, staat beschreven op Custom Elements: API-interfaces; hier behandelen we alles wat aan de andere kant van de lijn moet gebeuren.

Het idee in één zin: Skava kent uw domein niet. Het kent precies één formaat: de kaart. U bepaalt wat erop staat; wij controleren alleen de vorm, de afmetingen en de veiligheid. Een materiaalaanvraag is één voorbeeld; het volgende bedrijf verzamelt gebruikersfeedback, het daaropvolgende archiveren een foto van de bouwplaats in zijn eigen administratie.

Het proces in vogelvlucht

1. Een beheerder van het bedrijf maakt in Skava een API-element aan: een formulier plus het adres, de methode en het token van uw backend.
2. Iemand in de chat vult het formulier in en verzendt het.
3. Skava belt uw backend en stuurt de ingevulde waarden als JSON.
4. Uw antwoord wordt de kaart in de chat.
5. Optioneel rapporteert u later nieuwe statussen via de callback. Elk rapport wordt een nieuwe kaart; de vorige blijft staan.

Eisen voor uw backend

• HTTPS. Alleen https://, geen http, geen inloggegevens in het adres, maximaal 2000 tekens.
• Openbaar bereikbaar. De host moet uitsluitend op openbare IP-adressen wijzen. Localhost, privé-netwerken, link-local en cloud-metadata worden geweigerd en dit wordt bij elke aanroep gecontroleerd.
• Vast adres. Skava lost de host één keer op en koppelt de verbinding aan dat IP-adres. Een DNS-wijziging tijdens de aanroep heeft geen effect.
• Geen doorverwijzingen. Een 301 naar het "juiste" adres telt als een fout. Voer direct het eindadres in.
• Responstijd. De time-out is per element configureerbaar en hard gelimiteerd tot 30 seconden. Als u meer tijd nodig heeft, reageer dan onmiddellijk en rapporteer het resultaat later via de callback.
• Responsgrootte. Skava leest maximaal 256 KiB.
• Content-Type. De body wordt alleen verwerkt met application/json.

De aanvraag die u ontvangt

De methode is GET, POST, PUT of PATCH, afhankelijk van het element. Bij POST, PUT en PATCH komen de waarden binnen als JSON-body, bij GET als queryparameters.

Authenticatie is één header waarvan de naam en het voorvoegsel van de waarde in het element zijn geconfigureerd, meestal Authorization met het voorvoegsel Bearer . Het token is versleuteld opgeslagen aan onze kant. De headers host, content-length, content-type, cookie en accept-encoding kunnen niet worden ingesteld.

De body is een plat object. De sleutels worden gekozen door de maker van het element; geneste structuren komen alleen voor waar een tabel of een productkiezer is toegevoegd:

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

Drie sleutels komen altijd van ons, dus gebruik ze niet zelf:

• locale: de taalcodes van de gebruiker. Beantwoord in die taal; wij vertalen uw teksten niet.
• callback_url en callback_token: de callback voor deze interactie, zie hieronder. Ze zijn alleen aanwezig als het verzoek vanuit een chat komt.

Contextvelden zoals naam, bedrijf, project of subchat worden door de server zelf ingevuld, afgeleid van het kanaal waarin het element is uitgevoerd. Een gemanipuleerde client kan daar geen andere projectnaam claimen.

De respons: het kaartformaat

Antwoord met 2xx en een card-object. Dat is precies wat de kaart in de chat wordt:

{"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 (verplicht): het gehele getal 1. Als tekst ("1") wordt het afgewezen. Zonder dit telt het antwoord niet als kaart en wordt de in het element geconfigureerde responsmapping toegepast.
• title: de titel van de kaart.
• state: alleen kleur en ictoon, een van ok, pending, warn, error. Een onbekende waarde valt terug op ok en je krijgt een hint.
• status_text: vrije tekst die we niet interpreteren. Het staat bovenaan de kaart en wordt ook getoond in de chatlijst en in een pushmelding.
• velden: een lijst van label en value. Maximaal 20 items, label 80 tekens, value 200, title en status_text elk 120. Waarden die te lang zijn, worden verkort, niet afgewezen: een bestelling mag niet mislukken door een detail.
• icoon: zie hieronder.

Wat Skava met uw teksten doet voordat ze de chat bereiken: regeleinden en besturingskarakters worden verwijderd (een rechts-naar-links karakter zou anders de weergave van een bedrag kunnen omkeren), backticks worden vervangen en alles dat begint met [SKAVA: wordt onschadelijk gemaakt. Het laatste voorkomt dat een kaartwaarde als een ander chat-element wordt gelezen, bijvoorbeeld als een betalingsverzoek.

Links in velden, HTML en afbeeldingen kunnen niet worden ingesteld. Een chat is een vertrouwde omgeving en een klikbaar adres van een externe backend zou een uitnodiging zijn om een inlogpagina na te bouwen.

De invoer van de gebruiker is eigendom van de server: deze verschijnt op de eerste kaart en u kunt deze niet overschrijven. In de chat vormen ze het verslag van wat daadwerkelijk is ingediend.

Pictogrammen

Met icon krijgt de kaart zijn eigen markering in de koptekst. Twee opties:

Een naam uit de ingebouwde set: 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.

Of uw eigen SVG als tekenreeks. Skava neemt hieruit alleen de geometrie (path, circle, ellipse, rect, line, polyline, polygon met hun numerieke attributen) en bouwt zijn eigen afbeelding. Scripts, stijlen, externe referenties, foreignObject en gebeurtenisattributen worden verwaarloosd; een doctype of entiteit leidt tot afwijzing; het bestand mag maximaal 8 KiB zijn en maximaal 16 vormen bevatten. Kleur, lijndikte en grootte worden door Skava ingesteld, zodat een pictogram zich niet als een bedieningselement kan voordoen. Werk met een raster van 24 bij 24.

Zonder icon blijft de standaardmarkering behouden.

De callback: later statussen melden

De oproep bevat callback_url en callback_token. Gebruik deze om later nieuwe statussen te melden:

POST <callback_url> met Authorization: Bearer <callback_token> en Content-Type: application/json, body maximaal 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}

Naast de kaart zijn er drie optionele waarden:

• seq: uw eigen teller. Een melding met een kleinere of gelijke waarde wordt genegeerd, zodat twee meldingen elkaar niet kunnen inhalen. Zonder seq wint de laatst aangekomen melding.
• final: sluit de interactie af. Het token wordt ongeldig en er verschijnen geen verdere kaarten. Ook toegestaan in het eerste antwoord, voor flows zonder vervolg.
• notify: stel op false om de kaart stil te plaatsen, zonder onlezenaantal en zonder melding. Voor tussenstappen die niemand hoeven te wekken. Zonder deze instelling is de kaart een volwaardig bericht.

Elk rapport wordt een eigen kaart in de chat, de vorige blijft staan. Zo is leesbaar welke status gemeld werd. Hieruit volgt een aanbeveling: stuur alleen wat veranderd is. Een kaart die voor de vierde keer bestelnummer, items en totaal herhaalt, is voor de lezer alleen maar lawaai.

Twee limieten: hetzelfde rapport twee keer sturen produceert geen tweede kaart, en een interactie kan maximaal 50 kaarten plaatsen. Een interactie accepteert rapporten gedurende 90 dagen.

Antwoorden waarop je moet reageren

• 200 met {"result": "success", "updated": true, "seq": 3, "closed": false, "hints": []}. Lees de hints: ze zeggen wat is verkort of weggelaten.
• 401: verkeerde token of interactie-id. Niet opnieuw proberen.
• 410: interactie gesloten of verlopen. Niet opnieuw proberen.
• 422: kaart onbruikbaar, met hints als reden. Eerst oplossen.
• 400 gebroken JSON, 413 te groot, 429 te veel verzoeken (probeer opnieuw met back-off), 500 onze fout, probeer het later opnieuw.

Voorbeeld 1: een bestelling met een statusgeschiedenis

Stap 1, het verzoek aan uw 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"}

Stap 2, uw directe antwoord:

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

De chat toont nu een kaart met een pakketpictogram, de status en de invoer van de gebruiker.

Stap 3, later tijdens het plukken:

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

Een rustige tweede kaart zonder velden: alleen de status is gewijzigd.

Stap 4, bij verzending:

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}

Deze kaart kan iemand wakker maken, dus geen notify: false.

Stap 5, bij 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}

Met final is de interactie gesloten en werkt het token niet meer.

Voorbeeld 2: een actie zonder vervolgacties

Niet elke flow heeft een geschiedenis. Een element met één veld dat iets aan uw systeem doorgeeft, heeft slechts één antwoord nodig:

{"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 is hier van belang: anders blijft de interactie 90 dagen open met een geldige token, ook al rapporteert u nooit meer iets.

Productkiezer uit de catalogus

Zodra het bedrijf zijn artikelcatalogus heeft geüpload, kan het element het blok productkiezer bevatten. De gebruiker stelt hiermee een winkelwagen samen, en u ontvangt deze als een lijst onder de sleutel die door de maker van het element is gekozen:

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

Omdat de sleutel vrij is, zoek naar de eerste lijst met deze vorm in plaats van een vaste naam. Voordat Skava verzendt, controleert het of elk nummer daadwerkelijk bestaat in de catalogus van dat bedrijf, maximaal 50 items. In de kaart worden de items weergegeven als een lijst met productafbeelding, naam en hoeveelheid.

Testen

• Ping in de elementeditor verzendt een kale HEAD zonder token en zonder gegevens. Antwoord met wat dan ook; elke HTTP-antwoord telt als bereikbaar.
• Testaanvraag voert een echte oproep uit met voorbeeldwaarden, zelfs terwijl het element nog een concept is, en toont de aanvraag, het antwoord en de berichten van de kaartvalidator.
• Voorbeeld in het tabblad ernaast: plak je antwoord-JSON, controleer en je ziet de afgeronde kaart plus de hints. Het wordt op de server gecontroleerd met dezelfde code als in productie.
• Voorbeeldserver: een complete voorbeeldleverancier draait op api.skava.io en maakt gebruik van alles wat hierboven is beschreven. De broncode bevindt zich in de repository onder example_order_server/, ongeveer 600 regels pure standaardbibliotheek, bedoeld om te kopiëren.

Wat u nog meer moet weten

• De kaart is een volledig normale chatberichten. Het verschijnt in de zoekfunctie, kan worden aangehaald en blijft in de geschiedenis.
• Het wordt verzonden door de systeemzender, niet door een account van uw bedrijf. Het verschijnt nog steeds aan de kant van degene die het element heeft uitgevoerd, en in de titel staat welk systeem schrijft.
• Wie het mag uitvoeren, wordt ingesteld op het element: alleen leden van het bedrijf, of ook buitenstaanders die een chat met het bedrijf delen. Wanneer uw bedrijf de chat verlaat, vervalt de toestemming automatisch.
• Een API-element met een verlopen token is inactief en verschijnt niet eens in het menu totdat een beheerder een nieuw token opslaat.

Gerelateerd

Aanmaken en vrijgeven: Custom Elements: API-schnittstellen. Invulbare documenten in plaats van interfaces: Custom Elements: Documenten.