Call queueing

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.

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.

• 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.

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.

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

Open your agent in the dashboard, navigate to the Security tab, and scroll to Limits.

Toggle on Enable call queuing and set the Max queue wait time.

Under Custom hold audio, upload an MP3 or WAV file. You can preview the default hold tone and your uploaded clip before publishing.

Click Publish to apply the new settings.

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

Set platform_settings.queueing_config:

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

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

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

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,
    },
  },
});

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

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,
});

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

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

await elevenlabs.conversationalAi.agents.holdAudio.delete("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.

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.

No. A queued caller does not occupy a concurrency slot until they are connected to the agent.

Not currently. Queued callers hear the hold audio only. Queue position and wait-time estimates are not announced.

The caller leaves the queue immediately and everyone behind them moves up one place. No conversation minutes are charged.

No. Outbound and batch calls are only placed when capacity is available, so they are never queued.