POST/api/public/widget/message
Envoie un message du visiteur au chatbot et renvoie sa réponse – le point de terminaison central du widget de chat.
Envoyez `widget_code`, `message`, la `visitor_id` et – à partir du deuxième message – la `session_id` de la réponse précédente. Lors du premier appel d'une nouvelle conversation, laissez `session_id` vide ou définissez-la sur `null`. La réponse contient, dans l'objet `data`, la `session_id`, le texte de réponse `response` et, le cas échéant, des boutons (`buttons`), des suggestions de produits (`products`) et l'état de la conversation (`state`). L'en-tête `X-Widget-Token` avec le jeton d'intégration et `widget_code` sont requis. Si le jeton est manquant, le serveur répond 401 `WIDGET_TOKEN_MISSING`, s'il est invalide 401 `WIDGET_TOKEN_INVALID` ; les appels provenant de domaines non autorisés reçoivent 403 `WIDGET_ORIGIN_DENIED`, un widget désactivé 404 `WIDGET_DISABLED`. Si la `visitor_id` est manquante, le serveur répond 400 `VISITOR_ID_REQUIRED`. L'appel n'est pas idempotent : chaque envoi crée un nouveau message de visiteur et une nouvelle réponse. Verrouillez la saisie pendant qu'une requête est en cours et ne la répétez pas automatiquement.
Vue d'ensemble
Appel : POST /api/public/widget/message. Ce point de terminaison appartient au groupe « Widget de chat » de l'API de Zentor App. Il nécessite un jeton d'intégration de widget valide. L'appel n'est pas idempotent : chaque appel réussi déclenche à nouveau l'action. Paramètres obligatoires : widget_code (body), message (body), visitor_id (body). Paramètres facultatifs : session_id (body). Cas d'erreur documentés : 401 WIDGET_TOKEN_MISSING, 401 WIDGET_TOKEN_INVALID, 400 VISITOR_ID_REQUIRED. L'exemple de réponse ci-dessous montre la structure d'une réponse réussie au format JSON.
Authentification et sécurité
Jeton d'intégration du widget (en-tête X-Widget-Token) + liste d'origines autorisées
Idempotent: Non
Paramètres
widget_code(body, string, requis)— Code du widget provenant de votre code d'intégrationmessage(body, string, requis)— Texte du message du visiteurvisitor_id(body, string, requis)— Identifiant visiteur généré par le widget et stocké dans le navigateursession_id(body, string)— Identifiant de session de la réponse précédente ; vide ou `null` au premier appel d'une nouvelle conversationExemple de requête
{"widget_code":"...","message":"Bonjour, que peut faire Zentor App ?","visitor_id":"<UUID ou ID générée côté client>"}Exemple de réponse
{"ok":true,"data":{"session_id":"31b1096c-a366-4418-b4be-bd999ff98134","response":"...","buttons":[],"state":"idle","products":[]}}Codes d'erreur
401 WIDGET_TOKEN_MISSING — L'en-tête `X-Widget-Token` est manquant.401 WIDGET_TOKEN_INVALID — Le jeton d'intégration ne correspond pas au code du widget.400 VISITOR_ID_REQUIRED — Le champ `visitor_id` est manquant.Comportement vérifié
Un message valide renvoie 200 avec la réponse du chatbot ; un jeton manquant ou invalide ainsi qu'une `visitor_id` manquante renvoient les codes d'erreur documentés.
Widget de chat
GET /api/public/widget/healthVérification simple de disponibilité du service de widget.GET /api/public/widget/config/:widget_codeFournit la configuration publique d'un widget (nom d'affichage, message de bienvenue, design, langue, fonction vocale) pour l'initialisation dans le navigateur.GET /api/public/widget/historyCharge l'historique des messages précédents d'une conversation du widget, par exemple après le rechargement de la page.POST /api/public/widget/pollRécupère les messages reçus après un instant donné – par exemple la réponse d'un collaborateur ayant repris la conversation.POST /api/public/widget/ratingEnregistre l'évaluation du visiteur sur une conversation (utile ou non utile).POST /api/public/widget/trackEnregistre un événement d'utilisation anonyme du widget (p. ex. « widget ouvert ») pour les analyses dans le tableau de bord.POST /api/public/widget/voice-transcribeConvertit un enregistrement vocal du visiteur en texte (saisie vocale), si la fonction vocale est activée pour le widget.POST /api/public/widget/voice-speakConvertit un texte en parole (sortie vocale dans le widget), si la fonction vocale est activée.