Ir al contenido principal
Español— Elegir un idioma
Menú

Eventos de cliente a servidor

Lección 9 de 16 Actualizado el 30 de julio de 2026 Desarrollador
En esta página
  1. Los mensajes que envías
  2. conversation.item.create
  3. conversation.item.delete
  4. response.create y response.cancel
  5. Puntos clave

Los mensajes que envías

La API de Voice Agent funciona intercambiando eventos JSON a través de WebSocket. En esta lección, repasarás cada evento que tu aplicación puede enviar al servidor. Cada uno tiene un papel específico en el ciclo de la conversación.

Evento Descripción Cuándo usarlo
session.update Configurar la sesión Al inicio y para cambiar la configuración
input_audio_buffer.append Enviar un fragmento de audio en base64 De forma continua durante la grabación
input_audio_buffer.commit Confirmar el búfer de audio En modo pulsar para hablar (push-to-talk)
input_audio_buffer.clear Vaciar el búfer sin procesar Para cancelar una grabación
conversation.item.create Añadir un mensaje o resultado de función Historial, contexto, resultados de funciones
conversation.item.delete Eliminar un elemento por su ID Limpieza del historial de conversación
response.create Solicitar una respuesta En modo manual (automático con VAD)
response.cancel Cancelar una respuesta en curso Cuando el usuario interrumpe

conversation.item.create

Este evento te permite inyectar mensajes en la conversación sin pasar por el flujo de audio. Cubre tres casos principales.

Añadir un mensaje de texto de usuario

{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "¿Cuál es el estado de mi pedido 12345?"
      }
    ]
  }
}

Inyectar historial de conversación

Antes de que comience la conversación de voz, puedes prellenar el historial con intercambios anteriores para dar contexto al agente:

{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "Hola, soy tu asistente. ¿En qué puedo ayudarte?"
      }
    ]
  }
}

Devolver un resultado de función

Tras ejecutarse una llamada a función, envías el resultado con este evento (consulta la lección 13 sobre llamadas a funciones):

{
  "type": "conversation.item.create",
  "item": {
    "type": "function_call_output",
    "call_id": "call_abc123",
    "output": "{\"status\": \"shipped\", \"tracking\": \"FR123456789\"}"
  }
}

conversation.item.delete

Elimina un elemento de la conversación por su ID:

{
  "type": "conversation.item.delete",
  "item_id": "item_audio_001"
}

Esto resulta útil para eliminar un mensaje incorrecto o para evitar que el historial de la conversación crezca demasiado.

response.create y response.cancel

response.create solicita explícitamente al servidor que genere una respuesta. En modo VAD, el servidor lo hace por su cuenta una vez detecta el final del habla:

{
  "type": "response.create"
}

response.cancel detiene una respuesta que se está generando. Es útil cuando el usuario habla mientras lo hace el agente:

{
  "type": "response.cancel"
}

Puntos clave

  • Se pueden enviar ocho tipos de eventos del cliente al servidor
  • session.update configura la sesión y puede enviarse varias veces
  • conversation.item.create permite añadir texto, historial o resultados de funciones
  • response.create es necesario en modo manual y automático en modo VAD
  • response.cancel permite interrumpir al agente cuando el usuario vuelve a hablar