API du widget

Ces routes concernent les canaux WEBCHAT, pas les canaux API. Utilisez une clé widget nx_pub_ avec Authorization: Bearer <clé>. Dans un navigateur, fournissez une origine Origin autorisée par le canal. Les clés d'un canal API ne peuvent pas appeler ces routes, et les clés widget ne peuvent pas appeler POST /execute. Pour installer le widget, consultez Intégrer le widget webchat.

Configuration

GET /public/widget/config retourne channelId, apiKey, widgetId, theme, i18n, features, fileUpload et promptSuggestions. fileUpload vaut null si les fichiers sont désactivés ; sinon, il contient fieldName, maxFiles, maxSizeBytes et allowedMimeTypes.

Fichiers joints

POST /public/widget/uploads reçoit des données multipart/form-data dans le champ fileUpload.fieldName (ou files). La réponse 201 contient attachments : chaque entrée comporte attachmentId, name, mimeType et size. Les fichiers expirent après une heure et ne servent qu'à un message. Transmettez leurs identifiants dans attachmentIds de /public/widget/chat.

Dialogue

POST /public/widget/chat reçoit messages (messages AI SDK ; obligatoire), sessionId (UUID stable recommandé ; session_id est aussi accepté), et éventuellement attachmentIds, context, pageContext et stream. Seules les variables déclarées sur le canal sont conservées. stream vaut true par défaut ; sinon le texte arrive en une seule fois.

La réponse suit le format SSE AI SDK UI Message Stream, différent de celui de /execute. Elle n'a ni événement data-run ni marqueur [DONE]. Un nœud Question définit finish.messageMetadata.waitingForInput ; un transfert livechat définit finish.messageMetadata.livechatMode. Réutilisez le même sessionId pour garder l'historique ou répondre à la question.

Historique et livechat

GET /public/widget/conversations/{session_id}/messages retourne l'historique fusionné avec limit de 1 à 200 (défaut 50) et token_budget (défaut 0). Voir Lire les conversations pour les champs de réponse.

POST /public/widget/conversations/{session_id}/messages reçoit { "message": "..." } pendant le livechat actif. Hors de ce mode, il renvoie l'état actuel et une réponse immédiate ; voir Livechat. Cette route widget est distincte de l'ancienne route POST des canaux API.

POST /public/widget/conversations/{session_id}/presence retourne 204. À la fermeture de la page, sendBeacon peut envoyer depart avec ?api_key=<clé nx_pub_> ; ne journalisez pas cette URL.

POST /public/widget/conversations/{session_id}/supersede retourne 204 et annule le livechat actif ou en attente lors d'une demande explicite de nouvelle conversation. Ne l'appelez pas lors d'un rechargement ou d'une nouvelle tentative.

GET /public/conversations/{session_id}/stream transmet les événements livechat par SSE. Voir Livechat pour l'authentification, les événements et la reconnexion.

Les erreurs du widget ont actuellement deux formes : {"error":{"code":"http_error","message":"..."}} et {"error":"...","status":"error"}. Vérifiez d'abord le code HTTP.