Eventi dal client al server

Gli eventi dal client al server sono messaggi che la tua applicazione invia proattivamente al server per fornire contesto aggiuntivo durante le conversazioni. Questi eventi ti permettono di arricchire la conversazione con informazioni pertinenti senza interromperne il flusso.

Panoramica

La tua applicazione può inviare informazioni contestuali al server in qualsiasi momento durante la conversazione, per migliorarne qualità e pertinenza. Non deve necessariamente farlo in risposta a un evento client ricevuto dal server. Questa funzionalità è particolarmente utile per condividere lo stato dell’interfaccia utente, le azioni dell’utente o altri dati ambientali che potrebbero non essere comunicati direttamente tramite voce.

Tipi di eventi

Aggiornamenti contestuali

Gli aggiornamenti contestuali consentono alla tua applicazione di inviare informazioni di background alla conversazione senza interromperla.

Caratteristiche principali:

• Gli aggiornamenti vengono integrati nella conversazione come informazioni di background.
• Non interrompono il flusso della conversazione in corso.
• Sono utili per inviare lo stato dell’interfaccia utente, le azioni dell’utente o dati ambientali.

// 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");

Messaggi dell’utente

I messaggi dell’utente ti consentono di inviare testo direttamente alla conversazione come se l’utente lo avesse pronunciato. Sono utili per le interazioni basate su testo o quando vuoi inserire testo specifico nel flusso della conversazione.

Caratteristiche principali:

• Il testo viene elaborato come input dell’utente nella conversazione.
• Attiva lo stesso flusso di risposta dell’input vocale dell’utente.
• Sono utili per interfacce basate su testo o input utente programmatico.

// 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");

Attività dell’utente

Gli eventi di attività dell’utente fungono da indicatori per evitare interruzioni da parte dell’agente.

Caratteristiche principali:

• Reimpostano il timer di timeout del turno.
• Non influenzano il contenuto o il flusso della conversazione.
• Sono utili per mantenere conversazioni di lunga durata durante i periodi di silenzio.

// 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);

Best practice

1. Aggiornamenti contestuali

   • Invia informazioni contestuali pertinenti ma concise.
   • Evita di sovraccaricare l’LLM con troppi aggiornamenti.
   • Concentrati sulle informazioni che influenzano il flusso della conversazione o che costituiscono un contesto importante derivante dall’attività in un’interfaccia utente non accessibile all’agente vocale.

2. Messaggi dell’utente

   • Usali per l’input utente basato su testo quando l’audio non è disponibile o appropriato.
   • Assicurati che il contenuto testuale sia chiaro e ben formattato.
   • Considera il contesto della conversazione quando inserisci messaggi programmatici.

3. Attività dell’utente

   • Invia ping di attività durante i periodi di interazione dell’utente per mantenere la sessione.
   • Utilizza intervalli ragionevoli, ad esempio 30-60 secondi, per evitare traffico di rete non necessario.
   • Implementa il rilevamento dell’attività in base al coinvolgimento effettivo dell’utente, come il movimento del mouse o la digitazione.

4. Considerazioni sulla tempistica

   • Invia gli aggiornamenti nei momenti opportuni.
   • Valuta di raggruppare più aggiornamenti contestuali in un unico aggiornamento, invece di inviare separatamente ogni piccola modifica.
   • Trova un equilibrio tra mantenere attiva la sessione ed evitare una messaggistica eccessiva.