Widget de chat --- Next.js (`@mailoo/chat`)

Expón chat del sitio desde un host Next.js sin poner una clave API en el navegador. Usa @mailoo/chat para rutas BFF y el widget flotante opcional. Contrato de la API y notas de WebSocket: chat-widget{.interpreted-text role="doc"}, chat-websocket-production{.interpreted-text role="doc"}.

Flujo

1. El navegador llama solo a rutas del mismo origen en tu aplicación Next.js:

• POST /api/v1/webhooks/chat/submit --- cuerpo { "content": "...", "sessionPublicId?": "..." }
• GET /api/v1/webhooks/chat/messages?sessionPublicId=... --- polling opcional (since soportado)
• GET /api/v1/webhooks/chat/status --- estado opcional de la integración

2. El controlador de ruta reenvía a Mailoo con X-API-Key del entorno del servidor (createChatSubmitHandler / createChatMessagesHandler / createChatStatusHandler de @mailoo/chat/routes). Opcionalmente inyecta senderEmail / senderName mediante resolveSender para que el panel muestre la identidad del visitante en lugar de Guest.
3. Opcional: el widget abre WebSocket hacia la API. El host se resuelve en tiempo de ejecución en el servidor (sin NEXT_PUBLIC_* para el origen de la API):

• Orden por defecto: MAILOO_CHAT_WS_ORIGIN → MAILOO_CHAT_INTEGRATION_API → API_BASE_URL (getMailooChatWebSocketOrigin de @mailoo/chat)
• Establece MAILOO_CHAT_WS_ORIGIN cuando el nombre de host de la API visible para el navegador difiere de la URL que usa el servidor Node para llamar a la API

Superficie del paquete

// app/api/v1/webhooks/chat/submit/route.ts
import { createChatSubmitHandler } from '@mailoo/chat/routes'

export const POST = createChatSubmitHandler({
  resolveSender: async () => {
    const session = await auth()
    return session?.user?.email
      ? { email: session.user.email, name: session.user.name ?? undefined }
      : null
  },
})

// app/api/v1/webhooks/chat/messages/route.ts
import { createChatMessagesHandler } from '@mailoo/chat/routes'
export const GET = createChatMessagesHandler()

// app/api/v1/webhooks/chat/status/route.ts
import { createChatStatusHandler } from '@mailoo/chat/routes'
export const GET = createChatStatusHandler()

Sesión headless (UI personalizada) mediante @mailoo/chat/hooks:

import { useMailooChatSession } from '@mailoo/chat/hooks'

const chat = useMailooChatSession({
  apiOrigin,
  projectUid,
  integrationId,
  isAuthenticated,
  enabled: panelOpen,
})

Variables de entorno (solo servidor)

MAILOO_CHAT_INTEGRATION_API=https://api.mailoo.app
MAILOO_CHAT_INTEGRATION_API_KEY=your-api-key-here
MAILOO_CHAT_INTEGRATION_PROJECT_UID=your-project-uid
MAILOO_CHAT_INTEGRATION_ID=your-jsbox-integration-id
MAILOO_CHAT_WELCOME_MESSAGE=Hello! How can we help?

# Origen público opcional de la API para ws/wss cuando difiere de la URL de la API del servidor


# MAILOO_CHAT_WS_ORIGIN=https://api.mailoo.app

La clave API necesita chat.send-message (o FULL). Copia projectUid e integrationId desde Conexión y ajustes / fragmento de integración del panel de control.

Widget flotante

import { MailooSiteChatWidget } from '@mailoo/chat/client'

<MailooSiteChatWidget
  apiOrigin={wsOrigin}
  projectUid={projectUid}
  integrationId={integrationId}
  welcomeMessage={welcome}
  locale={locale}
  isAuthenticated={isAuthenticated}
/>

Consola de chat del panel de control

Para integraciones JSBOX, Abrir consola de chat abre la UI del operador para esa integración. Los operadores usan la sesión del panel; los visitantes usan el webhook público y las rutas WebSocket de arriba.

Relacionado

• chat-widget{.interpreted-text role="doc"} --- webhooks públicos y alcances
• chat-websocket-production{.interpreted-text role="doc"} --- notas de WebSocket en producción
• nextjs-packages{.interpreted-text role="doc"} --- resumen de paquetes