客户端到服务器事件

从客户端发送上下文信息，实时增强对话应用。

客户端到服务器事件是应用主动发送到服务器的消息，用于在对话期间提供额外上下文。这些事件可让你在不打断对话流程的情况下，补充相关信息。

如需了解服务器发送到客户端的事件，请参阅客户端事件文档。

概述

应用可在对话的任何阶段向服务器发送上下文信息，以提升对话质量和相关性。这无需响应从服务器收到的客户端事件。对于分享无法通过语音直接传达的 UI 状态、用户操作或其他环境数据，这尤其有用。

虽然我们的 SDK 提供了发送这些事件的辅助方法，但了解底层协议对于自定义实现和高级用例很有价值。

事件类型

上下文更新

上下文更新可让应用向对话发送不会造成中断的后台信息。

主要特性：

更新会作为对话的后台信息纳入。
不会中断当前对话流程。
适合发送 UI 状态、用户操作或环境数据。

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

用户消息

用户消息可让你将文本直接发送到对话中，如同用户说出了这段话。这适用于基于文本的交互，或需要向对话流程插入特定文本时。

主要特性：

文本将作为对话的用户输入处理。
会触发与语音用户输入相同的响应流程。
适合基于文本的界面或以编程方式提供用户输入。

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

用户活动

用户活动事件可作为信号，防止智能体打断用户。

主要特性：

重置轮次超时计时器。
不影响对话内容或流程。
适合在静默期间维持长时间对话。

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

最佳实践

上下文更新
- 发送相关且简洁的上下文信息。
- 避免用过多更新让 LLM 负担过重。
- 重点发送会影响对话流程的信息，或语音智能体无法获取的 UI 活动重要上下文。
用户消息
- 在无法或不适合使用音频时，用于接收基于文本的用户输入。
- 确保文本内容清晰且格式规范。
- 插入编程消息时，需考虑对话上下文。
用户活动
- 在用户交互期间发送活动 ping，以维持会话。
- 使用合理的时间间隔（例如 30-60 秒），避免不必要的网络流量。
- 根据实际用户参与情况（鼠标移动、输入等）实现活动检测。
时机考量
- 在适当时机发送更新。
- 考虑将多个上下文更新合并为一次更新（而非分别发送每个小改动）。
- 平衡维持会话与避免过多消息之间的关系。

如需详细实现示例，请查看我们的 SDK 文档。