Eventos de cliente a servidor
En esta página
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.updateconfigura la sesión y puede enviarse varias vecesconversation.item.createpermite añadir texto, historial o resultados de funcionesresponse.createes necesario en modo manual y automático en modo VADresponse.cancelpermite interrumpir al agente cuando el usuario vuelve a hablar