Conceptos

Última actualización: Aug 31, 2026Sección: Integraciones

Widget de chat (JSBOX)

El tipo de integración JSBOX alimenta el chat del sitio web: los visitantes envían mensajes que aparecen en tu panel de control de Mailoo. Puedes responder desde la consola de chat; los visitantes ven las actualizaciones mediante WebSocket o polling.

::: {.contents local=""} :::

Conceptos

  • Tipo de integración: JSBOX (creado en el panel de control o mediante la API pública con una clave API).
  • Sesiones: Cada hilo de visitante es una sesión de chat (sessionPublicId opaco). El primer mensaje crea una sesión; los mensajes posteriores incluyen sessionPublicId.
  • Clave API: Obligatoria para llamadas del lado del servidor a los webhooks de Mailoo (tu BFF, backend o automatización). Nunca pongas la clave API en JavaScript del navegador.

API pública (X-API-Key)

Las claves restringidas pueden incluir:

  • webhook.chat-integration-create --- POST /api/v1/webhooks/chat/{projectUid}/integrations (crear una integración JSBOX).
  • chat.send-message --- mensajes de chat, historial de sesión y estado de chat bajo /api/v1/webhooks/chat/....

Crear una integración JSBOX

curl -X POST "https://api.mailoo.app/api/v1/webhooks/chat/proj_1/integrations" \\
     -H "X-API-Key: YOUR_KEY" \\
     -H "Content-Type: application/json" \\
     -d '{"name":"Support chat","config":{"allowedOrigins":["https://example.com"]}}'

Enviar un mensaje de visitante (limitado a proyecto + integración):

curl -X POST "https://api.mailoo.app/api/v1/webhooks/chat/{projectUid}/{integrationId}/messages" \\
     -H "X-API-Key: YOUR_KEY" \\
     -H "Content-Type: application/json" \\
     -H "Origin: https://your-site.com" \\
     -d '{"content":"Hello","sessionPublicId":"optional-if-continuing"}'

Listar mensajes en una sesión (para polling servidor/BFF):

GET /api/v1/webhooks/chat/{projectUid}/{integrationId}/sessions/{sessionPublicId}/messages?since=ISO8601

Estado de la integración de chat

GET /api/v1/webhooks/chat/{projectUid}/{integrationId}/status

Ruta legada (solo id de integración): POST /api/v1/webhooks/messages/{integrationId} sigue existiendo pero requiere chat.send-message y una integración JSBOX.

Panel de control (JWT Bearer)

  • Sesiones: GET /api/v1/chat/{integrationId}/sessions
  • Historial: GET /api/v1/chat/{integrationId}/sessions/{sessionPublicId}/messages
  • Respuesta del propietario: POST /api/v1/chat/{integrationId}/sessions/{sessionPublicId}/reply con JSON {"content":"..."}.

La aplicación web las proxea a través de su BFF bajo las mismas rutas (con autenticación de sesión).

WebSocket

En un host Next.js usando @mailoo/chat, el origen WebSocket del navegador no es una variable de tiempo de compilación NEXT_PUBLIC_*: el servidor lo resuelve en tiempo de ejecución (MAILOO_CHAT_WS_ORIGIN, sino entorno base de chat/API --- consulta getMailooChatWebSocketOrigin).

  • Propietario (panel): /api/v1/chat/ws?integrationId=...&token=<JWT> --- usa el mismo token de acceso que Authorization: Bearer.
  • Visitante: /api/v1/chat/visitor-ws?projectUid=...&integrationId=...&sessionPublicId=... --- sin clave API; la sesión debe existir ya (creada al enviar un mensaje). Prefiere exponer solo sessionPublicId al navegador y validar en tu BFF cuando sea posible.

Para detalles de arquitectura, payloads de eventos, proxy inverso (wss) y consideraciones multi-réplica, consulta chat-websocket-production{.interpreted-text role="doc"}.

CORS y allowedOrigins

Las llamadas del navegador a los webhooks de Mailoo pueden enviar una cabecera Origin. Opcionalmente configura orígenes permitidos en la integración JSBOX. Si la lista está vacía, no se verifica Origin (la clave API sigue siendo obligatoria). El campo legado domain en la configuración almacenada permanece como respaldo CORS para filas antiguas pero ya no se recopila en el panel de control.

La posición del widget y el mensaje de bienvenida no son configuración de la integración --- establécelos en tu aplicación host (p. ej. props de @mailoo/chat o entorno del sitio).

Consulta también

  • chat-widget-nextjs-example{.interpreted-text role="doc"} --- patrón BFF de Next.js y variables de entorno
  • chat-websocket-production{.interpreted-text role="doc"} --- comportamiento WebSocket y notas de producción
  • OpenAPI: https://api.mailoo.app/docs/v1
📚