Client to server events

Client-to-server events are messages that your application proactively sends to the server to provide additional context during conversations. These events enable you to enhance the conversation with relevant information without interrupting the conversational flow.

Overview

Your application can send contextual information to the server to improve conversation quality and relevance at any point during the conversation. This does not have to be in response to a client event received from the server. This is particularly useful for sharing UI state, user actions, or other environmental data that may not be directly communicated through voice.

Contextual updates

The primary client-to-server event is the contextual update, which allows your application to send non-interrupting background information to the conversation.

Key characteristics:

• Updates are incorporated as background information in the conversation.
• Does not interrupt the current conversation flow.
• Useful for sending UI state, user actions, or environmental data.

1
// Contextual update event structure
2
{
3
  "type": "contextual_update",
4
  "text": "User appears to be looking at pricing page"
5
}

1
// Example sending contextual updates
2
function sendContextUpdate(information) {
3
  websocket.send(
4
    JSON.stringify({
5
      type: 'contextual_update',
6
      text: information,
7
    })
8
  );
9
}
10
11
// Usage examples
12
sendContextUpdate('Customer status: Premium tier');
13
sendContextUpdate('User navigated to Help section');
14
sendContextUpdate('Shopping cart contains 3 items');

Best practices

1. Contextual updates

   • Send relevant but concise contextual information.
   • Avoid overwhelming the LLM with too many updates.
   • Focus on information that impacts the conversation flow or is important context from activity in a UI not accessible to the voice agent.

2. Timing considerations

   • Send updates at appropriate moments.
   • Consider grouping multiple contextual updates into a single update (instead of sending every small change separately).