> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# 客户端到服务器事件

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

> **Note**
>
> 如需了解服务器发送到客户端的事件，请参阅[客户端 事件](/docs/zh/eleven-agents/customization/events/client-events)文档。

## 概述

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

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

## 事件类型

### 上下文更新

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

**主要特性：**

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

```javascript
// Contextual update event structure
{
  "type": "contextual_update",
  "text": "User appears to be looking at pricing page"
}
```

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

### 用户消息

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

**主要特性：**

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

```javascript
// User message event structure
{
  "type": "user_message",
  "text": "I would like to upgrade my account"
}
```

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

### 用户活动

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

**主要特性：**

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

```javascript
// User activity event structure
{
  "type": "user_activity"
}
```

```javascript
// Example sending user activity
function sendUserActivity() {
  websocket.send(
    JSON.stringify({
      type: "user_activity",
    })
  );
}

// Usage example - send activity ping every 30 seconds
setInterval(sendUserActivity, 30000);
```

## 最佳实践

1. **上下文更新**

   * 发送相关且简洁的上下文信息。
   * 避免用过多更新让 LLM 负担过重。
   * 重点发送会影响对话流程的信息，或语音智能体无法获取的 UI 活动重要上下文。

2. **用户消息**

   * 在无法或不适合使用音频时，用于接收基于文本的用户输入。
   * 确保文本内容清晰且格式规范。
   * 插入编程消息时，需考虑对话上下文。

3. **用户活动**

   * 在用户交互期间发送活动 ping，以维持会话。
   * 使用合理的时间间隔（例如 30-60 秒），避免不必要的网络流量。
   * 根据实际用户参与情况（鼠标移动、输入等）实现活动检测。

4. **时机考量**

   * 在适当时机发送更新。
   * 考虑将多个上下文更新合并为一次更新（而非分别发送每个小改动）。
   * 平衡维持会话与避免过多消息之间的关系。

> **Info**
>
> 如需详细实现示例，请查看我们的 [SDK 文档](/docs/zh/eleven-agents/libraries/python)。