Събития от сървър към клиент
На тази страница
Съобщенията, които получавате
Сървърът изпраща множество събития, за да Ви информира за състоянието на разговора, да достави аудио отговора и да докладва грешки. Разбирането на тези събития е от съществено значение за изграждането на отзивчиво и надеждно приложение.
Събития за сесията и разговора
Тези събития пристигат при стартиране на връзката и след всяка промяна в конфигурацията:
session.created: сесията е отворена; събитието съдържа конфигурацията на сесиятаsession.updated: конфигурацията е актуализирана успешноconversation.created: каналът за разговор е настроен
Събития за аудио буфера
Тези събития Ви информират за гласовата активност, открита от VAD (детектор на гласова активност):
input_audio_buffer.speech_started: VAD открива, че потребителят е започнал да говориinput_audio_buffer.speech_stopped: VAD открива края на речтаinput_audio_buffer.committed: аудио буферът е потвърден като съобщение
ws.on("message", (data) => {
const event = JSON.parse(data);
switch (event.type) {
case "input_audio_buffer.speech_started":
// Потребителят говори: покажете визуален индикатор
showSpeakingIndicator(true);
break;
case "input_audio_buffer.speech_stopped":
// Потребителят приключи: скрийте индикатора
showSpeakingIndicator(false);
break;
case "input_audio_buffer.committed":
// Аудио съобщението се обработва
showProcessingIndicator(true);
break;
}
});
Събития за аудио отговор
Аудио отговорът се предава чрез две събития.
response.output_audio.delta
Всяка делта съдържа чанк от аудио, кодиран в base64. Съберете ги и ги възпроизведете по ред:
{
"type": "response.output_audio.delta",
"delta": "SGVsbG8gV29ybGQ...",
"item_id": "item_resp_001",
"output_index": 0,
"content_index": 0
}
case "response.output_audio.delta":
const audioChunk = base64ToArrayBuffer(event.delta);
audioPlayer.enqueue(audioChunk);
break;
response.output_audio.done
Сигнализира, че цялото аудио на отговора е изпратено:
{
"type": "response.output_audio.done",
"item_id": "item_resp_001"
}
Събития за транскрипция
API може да транскрибира както аудио входа на потребителя, така и аудио отговора:
conversation.item.input_audio_transcription.completed: транскрипция на казаното от потребителяresponse.output_audio_transcript.delta: поточна транскрипция на отговора на агента
case "conversation.item.input_audio_transcription.completed":
console.log("Потребителят каза:", event.transcript);
displayUserMessage(event.transcript);
break;
case "response.output_audio_transcript.delta":
appendAgentTranscript(event.delta);
break;
Текстови събития
Ако агентът генерира текст (в допълнение към или вместо аудио), ще получите:
response.text.delta: поточен фрагмент от текст
{
"type": "response.text.delta",
"delta": "Вашата поръчка беше"
}
Събития за извикване на функции
Когато агентът реши да извика функция, се генерират две събития:
response.function_call_arguments.delta: аргументите на функцията, предавани поточноresponse.function_call_arguments.done: пълното извикване на функцията с всички нейни аргументи
Урок 13, посветен на извикването на гласови функции, разглежда тези събития подробно.
response.done
Това събитие маркира пълния край на отговора. То съдържа обобщение на отговора, включително статистика за използването:
{
"type": "response.done",
"response": {
"id": "resp_001",
"status": "completed",
"output": [...]
}
}
Събитието за грешка
Това събитие докладва грешки. Според референцията на xAI, повечето грешки са възстановими и WebSocket връзката остава отворена:
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "Невалиден аудио формат"
}
}
Вашето приложение трябва да регистрира тези грешки и, в зависимост от тяхната сериозност, да покаже съобщение на потребителя или да се опита да реши проблема автоматично.
Ключови изводи
- Сървърът изпраща събития за всяка стъпка: откриване на глас, аудио, транскрипция, текст и грешки
- Аудио отговорът пристига като base64 чанкове чрез
response.output_audio.delta - Транскрипциите са налични както за входа на потребителя, така и за изхода на агента
response.doneмаркира края на пълен отговор- Повечето грешки, докладвани чрез събитието
error, са възстановими: връзката остава отворена