POST/api/public/widget/message
Sender en besøkendes melding til chatboten og returnerer svaret – chat-widgetens sentrale endepunkt.
Send `widget_code`, `message`, `visitor_id` og – fra andre melding – `session_id` fra forrige svar. Ved første kall i en ny samtale lar du `session_id` være tom eller setter den til `null`. Svaret inneholder i objektet `data` `session_id`, svarteksten `response` samt eventuelt knapper (`buttons`), produktforslag (`products`) og samtaletilstand (`state`). Headeren `X-Widget-Token` med innbyggingstokenet og `widget_code` er obligatoriske. Mangler tokenet, svarer serveren med 401 `WIDGET_TOKEN_MISSING`, er det ugyldig, med 401 `WIDGET_TOKEN_INVALID`; kall fra domener som ikke er godkjent, får 403 `WIDGET_ORIGIN_DENIED`, en deaktivert widget 404 `WIDGET_DISABLED`. Mangler `visitor_id`, svarer serveren med 400 `VISITOR_ID_REQUIRED`. Kallet er ikke idempotent: Hver sending skaper en ny besøkendemelding og et nytt svar. Lås inndataene mens en forespørsel er under behandling, og gjenta den ikke automatisk.
Oversikt
Kall: POST /api/public/widget/message. Endepunktet tilhører gruppen «Chat-widget» i API-et til Zentor App. Det krever et gyldig widget-innbyggingstoken. Kallet er ikke idempotent: Hvert vellykket kall utløser handlingen på nytt. Obligatoriske parametere: widget_code (body), message (body), visitor_id (body). Valgfrie parametere: session_id (body). Dokumenterte feiltilfeller: 401 WIDGET_TOKEN_MISSING, 401 WIDGET_TOKEN_INVALID, 400 VISITOR_ID_REQUIRED. Eksempelsvaret nedenfor viser strukturen til et vellykket svar i JSON-format.
Autentisering og sikring
Widget-embed-token (header X-Widget-Token) + godkjenningsliste for origins
Idempotent: Nei
Parametere
widget_code(body, string, påkrevd)— Widget-kode fra innbyggingskoden dinmessage(body, string, påkrevd)— Teksten i den besøkendes meldingvisitor_id(body, string, påkrevd)— Besøkende-ID, som widgeten genererer og lagrer i nettleserensession_id(body, string)— Sesjons-ID fra forrige svar; tom eller `null` ved første kall i en ny samtaleEksempel på forespørsel
{"widget_code":"...","message":"Hei, hva kan Zentor App?","visitor_id":"<UUID eller klientgenerert ID>"}Eksempel på svar
{"ok":true,"data":{"session_id":"31b1096c-a366-4418-b4be-bd999ff98134","response":"...","buttons":[],"state":"idle","products":[]}}Feilkoder
401 WIDGET_TOKEN_MISSING — Headeren `X-Widget-Token` mangler.401 WIDGET_TOKEN_INVALID — Innbyggingstokenet samsvarer ikke med widget-koden.400 VISITOR_ID_REQUIRED — Feltet `visitor_id` mangler.Verifisert oppførsel
En gyldig melding returnerer 200 med chatbotens svar; et manglende eller ugyldig token samt en manglende `visitor_id` returnerer de dokumenterte feilkodene.
Chat-widget
GET /api/public/widget/healthEnkel tilgjengelighetskontroll av widget-tjenesten.GET /api/public/widget/config/:widget_codeReturnerer en widgets offentlige konfigurasjon (visningsnavn, velkomsttekst, design, språk, talefunksjon) for initialisering i nettleseren.GET /api/public/widget/historyLaster den tidligere meldingshistorikken til en widget-samtale, for eksempel etter at siden er lastet på nytt.POST /api/public/widget/pollHenter meldinger som er mottatt etter et gitt tidspunkt – for eksempel svaret fra en ansatt som har tatt over samtalen.POST /api/public/widget/ratingLagrer den besøkendes vurdering av en samtale (nyttig eller ikke nyttig).POST /api/public/widget/trackRegistrerer en anonym widget-brukshendelse (f.eks. «widget åpnet») for analysene i dashbordet.POST /api/public/widget/voice-transcribeKonverterer en besøkendes taleopptak til tekst (taleinnput), hvis talefunksjonen er aktivert for widgeten.POST /api/public/widget/voice-speakKonverterer tekst til tale (taleutgang i widgeten), hvis talefunksjonen er aktivert.