> 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/guides/burst-pricing)时的突发容量。

## 来电排队的工作方式

1. **容量检查**：来电接入时，ElevenAgents 会检查智能体和工作区是否有空闲并发名额。如有，来电会立即接通。
2. **排队**：如果没有可用名额，来电者会在智能体队列中等待并听到等待音频。等待期间不会开始对话，也不会产生费用。
3. **接入**：一旦有名额空出，队首来电者便会接通，对话照常开始。
4. **超时**：如果在 **最长队列等待时间** 内没有名额空出，通话将断开。电话通话会正常挂断。WebSocket 客户端会收到状态为 `timed_out` 的 `queue_status` 事件，随后连接会以代码 4300 关闭。

对于同一智能体，来电者严格按到达顺序接通。当多个智能体共享工作区并发池时，等待时间更长的来电者通常会优先接通。

### 来电者听到的内容

* 使用 Twilio 和 SIP 中继号码的电话来电者会在通话中听到等待音频。
* Widget 和浏览器 SDK 用户会在浏览器中听到等待音频。Widget（0.17.0 或更高版本）还会显示等待消息，并在排队期间禁用文本输入。
* 直接使用 WebSocket API 的客户端会收到常规 `audio` 事件形式的等待音频，以及用于在自定义 UI 中显示等待状态的 `queue_status` 事件。请参阅[在自定义 WebSocket 客户端中处理队列事件](#handling-queue-events-in-a-custom-websocket-client)。

### 计费和对话时长

在队列中等待的时间**不计费**，不计入智能体的**最长对话时长**，也不会包含在对话报告时长中。控制台中的对话详情会显示来电者接通前的等待时长。

## 支持的渠道

| 渠道                                       | 来电排队 |
| ---------------------------------------- | ---- |
| Twilio 呼入                                | 支持   |
| SIP 中继呼入                                 | 支持   |
| Widget 和客户端 SDK（WebSocket 和 WebRTC）      | 支持   |
| 直接 WebSocket API                         | 支持   |
| 呼出和批量通话                                  | 不支持  |
| 纯文本智能体                                   | 不支持  |
| Genesys、AudioCodes、Exotel、WhatsApp 和 SMS | 不支持  |

> **Note**
>
> 每日通话上限不会排队。超过智能体每日上限的通话会立即被拒绝，
> 因为该上限要到次日才会恢复。

## 配置

可在智能体 **Security** 标签页的 **Limits** 部分，按智能体配置来电排队。

| 设置           | 说明                                                                            | 默认值         |
| ------------ | ----------------------------------------------------------------------------- | ----------- |
| **启用来电排队**   | 智能体达到并发上限时，将来电者置于队列中等待。                                                       | 关闭          |
| **最长队列等待时间** | 通话断开前来电者可等待的秒数。范围为 1 到 1,800 秒（30 分钟）。                                        | 180 秒（3 分钟） |
| **自定义等待音频**  | 为排队来电者循环播放的 MP3 或 WAV 文件。最大 40 MB，最长 3 分钟。未上传文件时，来电者会听到默认等待音。可在控制台或通过 API 上传。 | 默认等待音       |

#### 通过控制台更新

#### 打开 Limits 设置

在控制台中打开智能体，进入 **Security** 标签页，然后滚动至 **Limits**。

#### 启用来电排队

开启 **Enable call queuing**，并设置 **Max queue wait time**。

#### 上传等待音频（可选）

在 **Custom hold audio** 下上传 MP3 或 WAV 文件。发布前可以预览默认等待音和上传的音频片段。

#### 发布更改

点击 **Publish** 应用新设置。

#### 通过 CLI 更新

#### 拉取智能体配置

```bash
elevenlabs agents pull --agent "<agent-name>"
```

#### 编辑 \`agent_configs/\<agent-name>.json\`

设置 `platform_settings.queueing_config`：

```json
{
  "platform_settings": {
    "queueing_config": {
      "enabled": true,
      "wait_timeout_seconds": 300
    }
  }
}
```

#### 推送更改

```bash
elevenlabs agents push --agent "<agent-name>"
```

#### 通过 API 更新

```python
from dotenv import load_dotenv
from elevenlabs import ElevenLabs
import os

load_dotenv()

elevenlabs = ElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)

elevenlabs.conversational_ai.agents.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    platform_settings={
        "queueing_config": {
            "enabled": True,
            "wait_timeout_seconds": 300,
        },
    },
)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import "dotenv/config";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", {
  platformSettings: {
    queueingConfig: {
      enabled: true,
      waitTimeoutSeconds: 300,
    },
  },
});
```

### 通过 API 管理等待音频

上传 MP3 或 WAV 文件可设置智能体的自定义等待音频。上传新文件会替换之前的文件。API 接受 `audio/mpeg` 和 `audio/wav` 内容类型，因此示例中明确设置了类型。

```python
from dotenv import load_dotenv
from elevenlabs import ElevenLabs
import os

load_dotenv()

elevenlabs = ElevenLabs(
api_key=os.getenv("ELEVENLABS_API_KEY"),
)

elevenlabs.conversational_ai.agents.hold_audio.create(
agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
hold_audio_file=("hold-music.mp3", open("hold-music.mp3", "rb"), "audio/mpeg"),
)

```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import fs from "node:fs";
import "dotenv/config";

const elevenlabs = new ElevenLabsClient();

const holdAudioFile = new File([fs.readFileSync("hold-music.mp3")], "hold-music.mp3", {
  type: "audio/mpeg",
});

await elevenlabs.conversationalAi.agents.holdAudio.create("agent_7101k5zvyjhmfg983brhmhkd98n6", {
  holdAudioFile,
});
```

移除自定义音频片段即可恢复默认等待音：

```python
elevenlabs.conversational_ai.agents.hold_audio.delete(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
)
```

```typescript
await elevenlabs.conversationalAi.agents.holdAudio.delete("agent_7101k5zvyjhmfg983brhmhkd98n6");
```

智能体会以只读字段 `platform_settings.queueing_config.hold_audio` 返回当前音频片段。在创建或更新智能体的请求中发送 `hold_audio` 不会生效。

## 在自定义 WebSocket 客户端中处理队列事件

通过 [WebSocket API](/docs/zh/eleven-agents/libraries/web-sockets) 连接的客户端在排队期间会收到 `queue_status` 事件：

```json
{
  "type": "queue_status",
  "queue_status_event": {
    "status": "waiting"
  }
}
```

* `waiting` 会在 `conversation_initiation_metadata` 后、任何等待音频前立即发送一次。
* 来电者接通时会发送 `admitted`。随后对话照常进行。
* 等待时间超过最长队列等待时间时会发送 `timed_out`。服务器随后会以代码 4300 关闭连接。

立即接通的通话永远不会收到 `queue_status` 事件。该事件始终发送给排队中的来电者，无需在智能体的 `client_events` 中启用。

只要智能体客户端事件包含 `audio`，等待音频就会以大约每秒一个片段的常规 `audio` 事件传送。应使用 `queue_status` 显示等待状态，而不要将等待音频视为智能体语音。

> **Info**
>
> `@elevenlabs/client` 和 `@elevenlabs/react` SDK 暂未提供此事件的专用回调。请使用
> `onIncomingEvent` 回调来监测原始服务器事件，包括
> `queue_status`。

## 常见问题

#### 排队中的通话会占用并发上限吗？

不会。排队中的来电者在接通智能体前不会占用并发名额。

#### 来电者能听到自己在队列中的位置或预计等待时间吗？

暂不支持。排队中的来电者只能听到等待音频，不会播报队列位置或预计等待时间。

#### 来电者在等待期间挂断会怎样？

来电者会立即离开队列，其后所有来电者都会前移一位。不会收取任何对话分钟费用。

#### 来电排队适用于呼出吗？

不适用。呼出和批量通话仅在有可用容量时才会发起，因此永远不会进入队列。