Eventos de cliente a servidor

Los eventos de cliente a servidor son mensajes que tu aplicación envía proactivamente al servidor para aportar contexto adicional durante las conversaciones. Estos eventos te permiten mejorar la conversación con información relevante sin interrumpir su flujo.

Resumen

Tu aplicación puede enviar información contextual al servidor en cualquier momento de la conversación para mejorar su calidad y relevancia. No es necesario que sea en respuesta a un evento de cliente recibido del servidor. Esto resulta especialmente útil para compartir el estado de la interfaz, acciones del usuario u otros datos del entorno que quizá no se comuniquen directamente por voz.

Tipos de eventos

Actualizaciones contextuales

Las actualizaciones contextuales permiten que tu aplicación envíe información de fondo a la conversación sin interrumpirla.

Características principales:

• Las actualizaciones se incorporan como información de fondo en la conversación.
• No interrumpen el flujo actual de la conversación.
• Son útiles para enviar el estado de la interfaz, acciones del usuario o datos del entorno.

// Contextual update event structure
{
  "type": "contextual_update",
  "text": "User appears to be looking at pricing page"
}

// Example sending contextual updates
function sendContextUpdate(information) {
  websocket.send(
    JSON.stringify({
      type: "contextual_update",
      text: information,
    })
  );
}
// Usage examples
sendContextUpdate("Customer status: Premium tier");
sendContextUpdate("User navigated to Help section");
sendContextUpdate("Shopping cart contains 3 items");

Mensajes del usuario

Los mensajes del usuario te permiten enviar texto directamente a la conversación como si el usuario lo hubiera dicho. Esto resulta útil para interacciones basadas en texto o cuando quieres introducir texto específico en el flujo de la conversación.

Características principales:

• El texto se procesa como entrada del usuario en la conversación.
• Activa el mismo flujo de respuesta que la entrada de voz del usuario.
• Es útil para interfaces basadas en texto o entradas de usuario programáticas.

// User message event structure
{
  "type": "user_message",
  "text": "I would like to upgrade my account"
}

// Example sending user messages
function sendUserMessage(text) {
  websocket.send(
    JSON.stringify({
      type: "user_message",
      text: text,
    })
  );
}
// Usage examples
sendUserMessage("I need help with billing");
sendUserMessage("What are your pricing options?");
sendUserMessage("Cancel my subscription");

Actividad del usuario

Los eventos de actividad del usuario sirven como indicadores para evitar que el agente interrumpa.

Características principales:

• Reinician el temporizador de tiempo de espera del turno.
• No afectan al contenido ni al flujo de la conversación.
• Son útiles para mantener conversaciones largas durante periodos de silencio.

// User activity event structure
{
  "type": "user_activity"
}

// Example sending user activity
function sendUserActivity() {
  websocket.send(
    JSON.stringify({
      type: "user_activity",
    })
  );
}
// Usage example - send activity ping every 30 seconds
setInterval(sendUserActivity, 30000);

Buenas prácticas

1. Actualizaciones contextuales

   • Envía información contextual relevante, pero concisa.
   • Evita saturar el LLM con demasiadas actualizaciones.
   • Céntrate en información que afecte al flujo de la conversación o que sea un contexto importante de la actividad en una interfaz a la que el agente de voz no pueda acceder.

2. Mensajes del usuario

   • Úsalos para entradas de usuario basadas en texto cuando el audio no esté disponible o no sea adecuado.
   • Asegúrate de que el contenido de texto sea claro y esté bien estructurado.
   • Ten en cuenta el contexto de la conversación al introducir mensajes programáticos.

3. Actividad del usuario

   • Envía pings de actividad durante los periodos de interacción del usuario para mantener la sesión.
   • Usa intervalos razonables (por ejemplo, de 30 a 60 segundos) para evitar tráfico de red innecesario.
   • Implementa la detección de actividad según la interacción real del usuario (movimiento del ratón, escritura, etc.).

4. Consideraciones sobre el momento

   • Envía actualizaciones en los momentos adecuados.
   • Considera agrupar varias actualizaciones contextuales en una sola actualización (en lugar de enviar cada cambio pequeño por separado).
   • Mantén un equilibrio entre conservar la sesión activa y evitar un exceso de mensajes.