Call queueing

Overview

When an agent or workspace reaches its concurrency limit, new calls are normally rejected immediately. With call queueing enabled, callers who arrive while the agent is at capacity are held on the line with hold audio and connected automatically, in the order they arrived, as soon as a slot frees up.

Call queueing is configured per agent and is turned off by default.

How call queueing works

1. Capacity check: When a call arrives, ElevenAgents checks whether the agent and the workspace have a free concurrency slot. If they do, the call connects immediately.
2. Queueing: If no slot is available, the caller is held in the agent’s queue and hears hold audio. No conversation starts and nothing is charged while the caller waits.
3. Admission: The moment a slot frees up, the caller at the front of the queue is connected and the conversation starts as usual.
4. Timeout: If no slot frees up within the Max queue wait time, the call is disconnected. Telephony calls are hung up normally. WebSocket clients receive a queue_status event with status timed_out, followed by a close with code 4300.

Callers are connected strictly in arrival order for a given agent. When several agents share a workspace’s concurrency pool, callers who have waited longer are generally connected first.

What the caller hears

• Phone callers on Twilio and SIP trunk numbers hear the hold audio over the call.
• Widget and browser SDK users hear the hold audio in the browser. The widget (version 0.17.0 or later) also shows a waiting message and disables text input while queued.
• Direct WebSocket API clients receive the hold audio as regular audio events, plus queue_status events to drive a waiting state in your own UI. See Handling queue events.

Billing and conversation duration

Time spent in the queue is not billed, does not count toward the agent’s Max conversation duration, and is not included in the conversation’s reported duration. The conversation details in the dashboard show how long the caller waited before being connected.

Supported channels

Configuration

Call queueing is configured per agent in the Limits section of the agent’s Security tab.

Managing hold audio through the API

Upload an MP3 or WAV file to set the agent’s custom hold audio. Uploading a new file replaces the previous one. The API accepts the audio/mpeg and audio/wav content types, so the examples set the type explicitly.

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

Remove the custom clip to return to the default hold tone:

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

The current clip is returned read-only as platform_settings.queueing_config.hold_audio on the agent. Sending hold_audio in an agent create or update request has no effect.

Handling queue events in a custom WebSocket client

Clients connected through the WebSocket API receive queue_status events while they are queued:

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

• waiting is sent once, immediately after conversation_initiation_metadata and before any hold audio.
• admitted is sent when the caller is connected. The conversation then proceeds as usual.
• timed_out is sent when the wait exceeds the max queue wait time. The server then closes the connection with code 4300.

Calls that connect immediately never receive queue_status events. The event is always sent to queued callers and does not need to be enabled in the agent’s client_events.

Hold audio is delivered as regular audio events in roughly one-second chunks, provided the agent’s client events include audio. Use queue_status to show a waiting state rather than treating the hold audio as agent speech.

FAQ