POST/api/public/widget/message

Envía un mensaje del visitante al chatbot y devuelve su respuesta — el endpoint central del widget de chat.

Envíe `widget_code`, `message`, la `visitor_id` y, a partir del segundo mensaje, la `session_id` de la respuesta anterior. En la primera llamada de una nueva conversación, deje `session_id` vacío o póngalo en `null`. La respuesta contiene, en el objeto `data`, la `session_id`, el texto de respuesta `response` y, si procede, botones (`buttons`), sugerencias de producto (`products`) y el estado de la conversación (`state`). El encabezado `X-Widget-Token` con el token de inserción y `widget_code` son obligatorios. Si falta el token, el servidor responde 401 `WIDGET_TOKEN_MISSING`; si es inválido, 401 `WIDGET_TOKEN_INVALID`; las llamadas desde dominios no autorizados reciben 403 `WIDGET_ORIGIN_DENIED`, y un widget desactivado, 404 `WIDGET_DISABLED`. Si falta `visitor_id`, el servidor responde 400 `VISITOR_ID_REQUIRED`. La llamada no es idempotente: cada envío crea otro mensaje del visitante y otra respuesta. Bloquee la entrada mientras una solicitud está en curso y no la repita automáticamente.

Descripción general

Llamada: POST /api/public/widget/message. Este endpoint pertenece al grupo «Widget de chat» de la API de Zentor App. Requiere un token de inserción de widget válido. La llamada no es idempotente: cada llamada correcta vuelve a desencadenar la acción. Parámetros obligatorios: widget_code (body), message (body), visitor_id (body). Parámetros opcionales: session_id (body). Casos de error documentados: 401 WIDGET_TOKEN_MISSING, 401 WIDGET_TOKEN_INVALID, 400 VISITOR_ID_REQUIRED. La respuesta de ejemplo siguiente muestra la estructura de una respuesta correcta en formato JSON.

Autenticación y seguridad

Token de inserción del widget (cabecera X-Widget-Token) + lista de orígenes permitidos

Idempotente: No

Parámetros

widget_code(body, string, obligatorio)— Código del widget de su código de inserción
message(body, string, obligatorio)— Texto del mensaje del visitante
visitor_id(body, string, obligatorio)— ID de visitante generado por el widget y almacenado en el navegador
session_id(body, string)— ID de sesión de la respuesta anterior; vacío o `null` en la primera llamada de una nueva conversación

Solicitud de ejemplo

{"widget_code":"...","message":"Hola, ¿qué puede hacer Zentor App?","visitor_id":"<UUID o ID generado por el cliente>"}

Respuesta de ejemplo

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

Códigos de error

401 WIDGET_TOKEN_MISSING — Falta el encabezado `X-Widget-Token`.
401 WIDGET_TOKEN_INVALID — El token de inserción no coincide con el código del widget.
400 VISITOR_ID_REQUIRED — Falta el campo `visitor_id`.

Comportamiento verificado

Un mensaje válido devuelve 200 con la respuesta del chatbot; un token faltante o inválido y una `visitor_id` faltante devuelven los códigos de error documentados.

Widget de chat

GET /api/public/widget/healthComprobación sencilla de disponibilidad del servicio de widget.GET /api/public/widget/config/:widget_codeDevuelve la configuración pública de un widget (nombre visible, mensaje de bienvenida, diseño, idioma, función de voz) para la inicialización en el navegador.GET /api/public/widget/historyCarga el historial de mensajes previo de una conversación del widget, por ejemplo tras recargar la página.POST /api/public/widget/pollObtiene los mensajes recibidos después de un momento dado, por ejemplo la respuesta de un empleado que ha asumido la conversación.POST /api/public/widget/ratingGuarda la valoración del visitante sobre una conversación (útil o no útil).POST /api/public/widget/trackRegistra un evento anónimo de uso del widget (p. ej., «widget abierto») para los análisis en el panel.POST /api/public/widget/voice-transcribeConvierte una grabación de voz del visitante en texto (entrada de voz), si la función de voz está activada para el widget.POST /api/public/widget/voice-speakConvierte texto en voz hablada (salida de voz en el widget), si la función de voz está activada.

Artículos relacionados

← Widget de chat