POST/api/public/widget/message

Stuurt een bericht van de bezoeker naar de chatbot en geeft diens antwoord terug — het centrale endpoint van de chatwidget.

Stuur `widget_code`, `message`, de `visitor_id` en — vanaf het tweede bericht — de `session_id` uit het vorige antwoord. Laat bij de eerste aanroep van een nieuw gesprek `session_id` leeg of zet deze op `null`. Het antwoord bevat in het object `data` de `session_id`, de antwoordtekst `response` en, indien van toepassing, knoppen (`buttons`), productsuggesties (`products`) en de gespreksstatus (`state`). De header `X-Widget-Token` met het embed-token en `widget_code` zijn verplicht. Ontbreekt het token, dan antwoordt de server met 401 `WIDGET_TOKEN_MISSING`; is het ongeldig, met 401 `WIDGET_TOKEN_INVALID`; aanroepen vanaf niet-goedgekeurde domeinen krijgen 403 `WIDGET_ORIGIN_DENIED`, een gedeactiveerde widget 404 `WIDGET_DISABLED`. Ontbreekt `visitor_id`, dan antwoordt de server met 400 `VISITOR_ID_REQUIRED`. De aanroep is niet idempotent: elke verzending maakt weer een bezoekersbericht en weer een antwoord aan. Blokkeer de invoer zolang een aanvraag loopt en herhaal deze niet automatisch.

Overzicht

Aanroep: POST /api/public/widget/message. Dit endpoint hoort bij de groep ‘Chatwidget’ van de API van Zentor App. Het vereist een geldig widget-embedtoken. De aanroep is niet idempotent: elke geslaagde aanroep activeert de actie opnieuw. Verplichte parameters: widget_code (body), message (body), visitor_id (body). Optionele parameters: session_id (body). Gedocumenteerde foutgevallen: 401 WIDGET_TOKEN_MISSING, 401 WIDGET_TOKEN_INVALID, 400 VISITOR_ID_REQUIRED. Het voorbeeldantwoord hieronder toont de opbouw van een geslaagd antwoord in JSON-formaat.

Auth & beveiliging

Widget-embed-token (header X-Widget-Token) + origin-toestemmingslijst

Idempotent: Nee

Parameters

widget_code(body, string, vereist)— Widgetcode uit uw embedcode
message(body, string, vereist)— Tekst van het bezoekersbericht
visitor_id(body, string, vereist)— Bezoeker-ID die de widget genereert en in de browser opslaat
session_id(body, string)— Sessie-ID uit het vorige antwoord; leeg of `null` bij de eerste aanroep van een nieuw gesprek

Voorbeeld-request

{"widget_code":"...","message":"Hoi, wat kan Zentor App?","visitor_id":"<UUID of door de client gegenereerde ID>"}

Voorbeeld-response

{"ok":true,"data":{"session_id":"31b1096c-a366-4418-b4be-bd999ff98134","response":"...","buttons":[],"state":"idle","products":[]}}

Foutcodes

401 WIDGET_TOKEN_MISSING — De header `X-Widget-Token` ontbreekt.
401 WIDGET_TOKEN_INVALID — Het embed-token past niet bij de widgetcode.
400 VISITOR_ID_REQUIRED — Het veld `visitor_id` ontbreekt.

Geverifieerd gedrag

Een geldig bericht geeft 200 met het antwoord van de chatbot; een ontbrekend of ongeldig token en een ontbrekende `visitor_id` geven de gedocumenteerde foutcodes.

Chatwidget

GET /api/public/widget/healthEenvoudige bereikbaarheidscontrole van de widgetservice.GET /api/public/widget/config/:widget_codeGeeft de publieke configuratie van een widget (weergavenaam, welkomsttekst, vormgeving, taal, spraakfunctie) voor initialisatie in de browser.GET /api/public/widget/historyLaadt de eerdere berichtgeschiedenis van een widgetgesprek, bijvoorbeeld na het opnieuw laden van de pagina.POST /api/public/widget/pollHaalt berichten op die na een bepaald tijdstip zijn ontvangen — bijvoorbeeld het antwoord van een medewerker die het gesprek heeft overgenomen.POST /api/public/widget/ratingSlaat de beoordeling van de bezoeker over een gesprek op (nuttig of niet nuttig).POST /api/public/widget/trackRegistreert een anoniem gebruiksevent van de widget (bijv. “widget geopend”) voor de analyses in het dashboard.POST /api/public/widget/voice-transcribeZet een spraakopname van de bezoeker om in tekst (spraakinvoer), als de spraakfunctie voor de widget is geactiveerd.POST /api/public/widget/voice-speakZet tekst om in gesproken taal (spraakuitvoer in de widget), als de spraakfunctie is geactiveerd.

Gerelateerde artikelen

← Chatwidget