呼叫排队

概述

当智能体或工作区达到并发上限时，新来电通常会立即被拒绝。启用来电排队后，智能体满负荷时接入的来电者会在通话中等待并听到等待音频；一旦有空余名额，将按到达顺序自动接通。

来电排队按智能体配置，默认关闭。

来电排队的工作方式

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 客户端中处理队列事件。

计费和对话时长

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

支持的渠道

配置

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

通过 API 管理等待音频

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

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"),
)

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

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

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

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

通过 WebSocket API 连接的客户端在排队期间会收到 queue_status 事件：

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

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

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

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

常见问题