WebChat

El canal WebChat proporciona un widget de chat embebible integrado que se conecta a su agente Triggerfish a través de WebSocket. Está diseñado para interacciones orientadas al cliente, widgets de soporte o cualquier escenario donde desee ofrecer una experiencia de chat basada en web.

Clasificación por defecto

WebChat tiene por defecto la clasificación PUBLIC. Este es un valor fijo por defecto por una razón: los visitantes web nunca se tratan como propietarios. Cada mensaje de una sesión WebChat lleva contaminación PUBLIC independientemente de la configuración.

Los visitantes nunca son propietarios A diferencia de otros canales

donde la identidad del propietario se verifica por ID de usuario o número de teléfono, WebChat establece isOwner: false para todas las conexiones. Esto significa que el agente nunca ejecutará comandos de nivel propietario desde una sesión WebChat. Esta es una decisión de seguridad deliberada -- no se puede verificar la identidad de un visitante web anónimo. :::

Configuración

Paso 1: Configurar Triggerfish

Añada el canal WebChat a su triggerfish.yaml:

channels:
  webchat:
    port: 8765
    allowedOrigins:
      - "https://su-sitio.com"

Opción	Tipo	Obligatorio	Descripción
port	number	No	Puerto del servidor WebSocket (por defecto: 8765)
classification	string	No	Nivel de clasificación (por defecto: PUBLIC)
allowedOrigins	string[]	No	Orígenes CORS permitidos (por defecto: ["*"])

Paso 2: Iniciar Triggerfish

triggerfish stop && triggerfish start

El servidor WebSocket comienza a escuchar en el puerto configurado.

Paso 3: Conectar un widget de chat

Conéctese al endpoint WebSocket desde su aplicación web:

const ws = new WebSocket("ws://localhost:8765");

ws.onopen = () => {
  console.log("Connected to Triggerfish");
};

ws.onmessage = (event) => {
  const frame = JSON.parse(event.data);

  if (frame.type === "session") {
    // El servidor asignó un ID de sesión
    console.log("Session:", frame.sessionId);
  }

  if (frame.type === "message") {
    // Respuesta del agente
    console.log("Agent:", frame.content);
  }
};

// Enviar un mensaje
function sendMessage(text) {
  ws.send(JSON.stringify({
    type: "message",
    content: text,
  }));
}

Cómo funciona

Flujo de conexión

1. Un cliente del navegador abre una conexión WebSocket al puerto configurado
2. Triggerfish actualiza la petición HTTP a WebSocket
3. Se genera un ID de sesión único (webchat-<uuid>)
4. El servidor envía el ID de sesión al cliente en un frame session
5. El cliente envía y recibe frames message como JSON

Formato de los frames de mensaje

Todos los mensajes son objetos JSON con esta estructura:

{
  "type": "message",
  "content": "Hello, how can I help?",
  "sessionId": "webchat-a1b2c3d4-..."
}

Tipos de frame:

Tipo	Dirección	Descripción
session	Servidor a cliente	Enviado en la conexión con el ID de sesión asignado
message	Ambas	Mensaje de chat con contenido de texto
ping	Ambas	Ping de keep-alive
pong	Ambas	Respuesta de keep-alive

Gestión de sesiones

Cada conexión WebSocket obtiene su propia sesión. Cuando la conexión se cierra, la sesión se elimina del mapa de conexiones activas. No hay reanudación de sesión -- si la conexión se interrumpe, se asigna un nuevo ID de sesión al reconectar.

Comprobación de estado

El servidor WebSocket también responde a peticiones HTTP normales con una comprobación de estado:

curl http://localhost:8765
# Respuesta: "WebChat OK"

Esto es útil para comprobaciones de estado de balanceadores de carga y monitorización.

Indicadores de escritura

Triggerfish envía y recibe indicadores de escritura a través de WebChat. Cuando el agente está procesando, se envía un frame de indicador de escritura al cliente. El widget puede mostrarlo para indicar que el agente está pensando.

Consideraciones de seguridad

• Todos los visitantes son externos -- isOwner es siempre false. El agente no ejecutará comandos del propietario desde WebChat.
• Contaminación PUBLIC -- Cada mensaje se contamina con PUBLIC a nivel de sesión. El agente no puede acceder ni devolver datos por encima de la clasificación PUBLIC en una sesión WebChat.
• CORS -- Configure allowedOrigins para restringir qué dominios pueden conectarse. El valor por defecto ["*"] permite cualquier origen, lo cual es apropiado para desarrollo pero debería restringirse en producción.

Restrinja los orígenes en producción Para despliegues en producción,

especifique siempre sus orígenes permitidos explícitamente:

channels:
  webchat:
    port: 8765
    allowedOrigins:
      - "https://su-dominio.com"
      - "https://app.su-dominio.com"

Cambiar la clasificación

Aunque WebChat tiene por defecto PUBLIC, técnicamente puede establecerlo a un nivel diferente. Sin embargo, dado que isOwner es siempre false, la clasificación efectiva para todos los mensajes permanece PUBLIC debido a la regla de clasificación efectiva (min(canal, destinatario)).

channels:
  webchat:
    port: 8765
    classification: INTERNAL # Permitido, pero isOwner sigue siendo false

Niveles válidos: PUBLIC, INTERNAL, CONFIDENTIAL, RESTRICTED.