Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Avvenimenti mis-server għall-klijent

Lezzjoni 10 / 16 Aġġornat 30 ta’ Lulju 2026 Zviluppatur
F'din il-paġna
  1. Il-messaġġi li tirċievi
  2. Avvenimenti tas-sessjoni u tal-konversazzjoni
  3. Avvenimenti tal-buffer tal-awdjo
  4. Avvenimenti tal-awdjo tar-risposta
  5. Avvenimenti tat-traskrizzjoni
  6. Avvenimenti tat-test
  7. Avvenimenti tas-sejħa tal-funzjonijiet
  8. response.done
  9. L-avveniment tal-iżball
  10. Punti Ewlenin

Il-messaġġi li tirċievi

Is-server jibgħat ħafna avvenimenti biex iżommok infurmat dwar l-istat tal-konversazzjoni, iwassal l-awdjo tar-risposta, u jirrapporta l-iżbalji. Li tifhem dawn l-avvenimenti huwa essenzjali biex tibni app reattiva u affidabbli.

Avvenimenti tas-sessjoni u tal-konversazzjoni

Dawn l-avvenimenti jaslu meta tinbeda l-konnessjoni u wara kull bidla fil-konfigurazzjoni:

  • session.created: is-sessjoni miftuħa; l-avveniment fih il-konfigurazzjoni tas-sessjoni
  • session.updated: il-konfigurazzjoni ġiet aġġornata b’suċċess
  • conversation.created: il-kanal tal-konversazzjoni ġie stabbilit

Avvenimenti tal-buffer tal-awdjo

Dawn l-avvenimenti jgħidulek dwar l-attività tal-vuċi li jiskopri l-VAD:

  • input_audio_buffer.speech_started: il-VAD jiskopri li l-utent beda jitkellem
  • input_audio_buffer.speech_stopped: il-VAD jiskopri t-tmiem tad-diskors
  • input_audio_buffer.committed: il-buffer tal-awdjo ġie kkonfermat bħala messaġġ
ws.on("message", (data) => {
  const event = JSON.parse(data);

  switch (event.type) {
    case "input_audio_buffer.speech_started":
      // L-utent qed jitkellem: uri indikatur viżiv
      showSpeakingIndicator(true);
      break;

    case "input_audio_buffer.speech_stopped":
      // L-utent spiċċa: aħbi l-indikatur
      showSpeakingIndicator(false);
      break;

    case "input_audio_buffer.committed":
      // Il-messaġġ tal-awdjo qed jiġi pproċessat
      showProcessingIndicator(true);
      break;
  }
});

Avvenimenti tal-awdjo tar-risposta

L-awdjo tar-risposta jiġi trasmess permezz ta’ żewġ avvenimenti.

response.output_audio.delta

Kull delta fiha biċċa awdjo kodifikata f’base64. Iġborhom u daqqhom fl-ordni:

{
  "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

Jissinjala li l-awdjo kollu tar-risposta ntbagħat:

{
  "type": "response.output_audio.done",
  "item_id": "item_resp_001"
}

Avvenimenti tat-traskrizzjoni

L-API tista’ ttraskrivi kemm l-awdjo tal-utent kif ukoll l-awdjo tar-risposta:

  • conversation.item.input_audio_transcription.completed: traskrizzjoni ta’ dak li qal l-utent
  • response.output_audio_transcript.delta: traskrizzjoni fluss tad-diskors tal-aġent
case "conversation.item.input_audio_transcription.completed":
  console.log("User said:", event.transcript);
  displayUserMessage(event.transcript);
  break;

case "response.output_audio_transcript.delta":
  appendAgentTranscript(event.delta);
  break;

Avvenimenti tat-test

Jekk l-aġent jiġġenera test (minflok jew flimkien mal-awdjo), tirċievi:

  • response.text.delta: framment ta’ test trasmess
{
  "type": "response.text.delta",
  "delta": "Your order has been"
}

Avvenimenti tas-sejħa tal-funzjonijiet

Meta l-aġent jiddeċiedi li jsejjaħ funzjoni, jinħarġu żewġ avvenimenti:

  • response.function_call_arguments.delta: l-argumenti tal-funzjoni, trasmessi
  • response.function_call_arguments.done: is-sejħa sħiħa tal-funzjoni bl-argumenti kollha tagħha

Il-Lezzjoni 13, dwar is-sejħa tal-funzjonijiet bil-vuċi, tkopri dawn l-avvenimenti fid-dettall.

response.done

Dan l-avveniment jimmarka t-tmiem sħiħ ta’ risposta. Fih sommarju tar-risposta, inklużi statistiċi dwar l-użu:

{
  "type": "response.done",
  "response": {
    "id": "resp_001",
    "status": "completed",
    "output": [...]
  }
}

L-avveniment tal-iżball

Dan l-avveniment jirrapporta l-iżbalji. Skont ir-referenza ta’ xAI, ħafna żbalji huma rekuperabbli u l-konnessjoni WebSocket tibqa’ miftuħa:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid audio format specified"
  }
}

L-app tiegħek għandha tirreġistra dawn l-iżbalji u, skont kemm huma serji, turi messaġġ lill-utent jew tipprova ssolvi l-problema awtomatikament.

Punti Ewlenin

  • Is-server jibgħat avvenimenti għal kull pass: skoperta tal-vuċi, awdjo, traskrizzjoni, test u żbalji
  • L-awdjo tar-risposta jasal f’biċċiet base64 permezz ta’ response.output_audio.delta
  • It-traskrizzjonijiet huma disponibbli kemm għad-dħul tal-utent kif ukoll għall-output tal-aġent
  • response.done jimmarka t-tmiem ta’ risposta sħiħa
  • Ħafna żbalji rrapportati permezz tal-avveniment error huma rekuperabbli: il-konnessjoni tibqa’ miftuħa