> 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. # Cola de llamadas ## Resumen Cuando un agente o espacio de trabajo alcanza su límite de concurrencia, las nuevas llamadas normalmente se rechazan de inmediato. Con la cola de llamadas activada, quienes llaman mientras el agente está al máximo de su capacidad se mantienen en línea con audio de espera y se conectan automáticamente, en el orden en que llegaron, en cuanto queda un puesto libre. La cola de llamadas se configura por agente y está activada de forma predeterminada en los agentes nuevos. > **Note** > > La cola de llamadas se aplica una vez que se ha agotado toda la capacidad disponible, incluida la capacidad adicional cuando se ha activado el [precio por capacidad adicional](/docs/es/eleven-agents/guides/burst-pricing) para el agente. ## Cómo funciona la cola de llamadas 1. **Comprobación de capacidad**: Cuando llega una llamada, ElevenAgents comprueba si el agente y el espacio de trabajo tienen un puesto de concurrencia libre. Si lo tienen, la llamada se conecta inmediatamente. 2. **Cola**: Si no hay ningún puesto disponible, quien llama se mantiene en la cola del agente y escucha audio de espera. No se inicia ninguna conversación ni se cobra nada mientras espera. 3. **Admisión**: En cuanto queda un puesto libre, se conecta a quien está al principio de la cola y la conversación comienza como de costumbre. 4. **Tiempo de espera agotado**: Si no queda ningún puesto libre dentro del **Tiempo máximo de espera en cola**, la llamada se desconecta. Las llamadas de telefonía se cuelgan con normalidad. Los clientes WebSocket reciben un evento `queue_status` con el estado `timed_out`, seguido de un cierre con el código 4300. Quienes llaman se conectan estrictamente por orden de llegada para un agente concreto. Cuando varios agentes comparten el grupo de concurrencia de un espacio de trabajo, normalmente se conecta primero a quienes llevan más tiempo esperando. ### Lo que escucha quien llama * Quienes llaman por teléfono mediante números de Twilio y troncales SIP escuchan el audio de espera durante la llamada. * Usuarios del widget y de los SDK de navegador escuchan el audio de espera en el navegador. El widget (versión 0.17.0 o posterior) también muestra un mensaje de espera y desactiva la entrada de texto mientras están en cola. * Los clientes directos de la API WebSocket reciben el audio de espera como eventos `audio` normales, además de eventos `queue_status` para controlar un estado de espera en tu propia interfaz. Consulta [Gestionar eventos de cola](#handling-queue-events-in-a-custom-websocket-client). ### Facturación y duración de la conversación El tiempo en cola **no se factura**, no cuenta para la **Duración máxima de conversación** del agente y no se incluye en la duración indicada de la conversación. Los detalles de la conversación en el panel muestran cuánto tiempo esperó quien llamó antes de conectarse. ## Canales compatibles | Canal | Cola de llamadas | | -------------------------------------------- | ---------------- | | Llamadas entrantes de Twilio | Compatible | | Llamadas entrantes de troncales SIP | Compatible | | Widget y SDK de cliente (WebSocket y WebRTC) | Compatible | | API WebSocket directa | Compatible | | Llamadas salientes y llamadas por lotes | No compatible | | Agentes solo de texto | No compatible | | Genesys, AudioCodes, Exotel, WhatsApp y SMS | No compatible | > **Note** > > El límite diario de llamadas no se pone en cola. Una llamada que supera el límite diario del agente se rechaza > inmediatamente, porque ese límite no se libera hasta el día siguiente. ## Configuración La cola de llamadas se configura por agente en la sección **Límites** de la pestaña **Seguridad** del agente. | Ajuste | Descripción | Predeterminado | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | | **Activar cola de llamadas** | Mantén a quienes llaman en una cola cuando el agente alcance su límite de concurrencia. | Activado | | **Tiempo máximo de espera en cola** | Cuánto tiempo puede esperar quien llama antes de que se desconecte la llamada, en segundos. Entre 1 y 1800 segundos (30 minutos). | 180 segundos (3 minutos) | | **Audio de espera personalizado** | Un archivo MP3 o WAV que se reproduce en bucle para quienes están en cola. Hasta 40 MB y 3 minutos de duración. Si no se sube ningún archivo, quienes llaman escuchan el tono de espera predeterminado. Súbelo en el panel o mediante la API. | Tono de espera predeterminado | #### Actualizar desde el panel #### Abre los ajustes de Límites Abre tu agente en el panel, ve a la pestaña **Seguridad** y desplázate hasta **Límites**. #### Activa la cola de llamadas Asegúrate de que **Activar cola de llamadas** esté activado y configura el **Tiempo máximo de espera en cola**. #### Sube audio de espera (opcional) En **Audio de espera personalizado**, sube un archivo MP3 o WAV. Puedes previsualizar el tono de espera predeterminado y el clip que has subido antes de publicar. #### Publica los cambios Haz clic en **Publicar** para aplicar los nuevos ajustes. #### Actualizar mediante la CLI #### Obtén la configuración del agente ```bash elevenlabs agents pull --agent "" ``` #### Edita \`agent_configs/\.json\` Configura `platform_settings.queueing_config`: ```json { "platform_settings": { "queueing_config": { "enabled": true, "wait_timeout_seconds": 300 } } } ``` #### Envía los cambios ```bash elevenlabs agents push --agent "" ``` #### Actualizar mediante la 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, }, }, }); ``` Los agentes nuevos se crean con `queueing_config.enabled` establecido en `true`. Para crear un agente con la cola de llamadas desactivada, establece `queueing_config.enabled` en `false` en la solicitud de creación. ### Gestionar el audio de espera mediante la API Sube un archivo MP3 o WAV para configurar el audio de espera personalizado del agente. Al subir un archivo nuevo, se sustituye el anterior. La API acepta los tipos de contenido `audio/mpeg` y `audio/wav`, por lo que los ejemplos establecen el tipo explícitamente. ```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, }); ``` Elimina el clip personalizado para volver al tono de espera predeterminado: ```python elevenlabs.conversational_ai.agents.hold_audio.delete( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", ) ``` ```typescript await elevenlabs.conversationalAi.agents.holdAudio.delete("agent_7101k5zvyjhmfg983brhmhkd98n6"); ``` El clip actual se devuelve como de solo lectura en `platform_settings.queueing_config.hold_audio` del agente. Enviar `hold_audio` en una solicitud de creación o actualización de agente no tiene efecto. ## Gestionar eventos de cola en un cliente WebSocket personalizado Los clientes conectados mediante la [API WebSocket](/docs/es/eleven-agents/libraries/web-sockets) reciben eventos `queue_status` mientras están en cola: ```json { "type": "queue_status", "queue_status_event": { "status": "waiting" } } ``` * `waiting` se envía una vez, inmediatamente después de `conversation_initiation_metadata` y antes de cualquier audio de espera. * `admitted` se envía cuando se conecta a quien llama. La conversación continúa entonces como de costumbre. * `timed_out` se envía cuando la espera supera el tiempo máximo de espera en cola. El servidor cierra entonces la conexión con el código 4300. Las llamadas que se conectan inmediatamente nunca reciben eventos `queue_status`. El evento siempre se envía a quienes están en cola y no es necesario activarlo en los `client_events` del agente. El audio de espera se entrega como eventos `audio` normales en fragmentos de aproximadamente un segundo, siempre que los eventos de cliente del agente incluyan `audio`. Usa `queue_status` para mostrar un estado de espera en lugar de tratar el audio de espera como voz del agente. > **Info** > > Los SDK `@elevenlabs/client` y `@elevenlabs/react` todavía no exponen una devolución de llamada específica para este > evento. Usa la devolución de llamada `onIncomingEvent` para observar eventos sin procesar del servidor, incluido > `queue_status`. ## Preguntas frecuentes #### ¿Una llamada en cola cuenta para mi límite de concurrencia? No. Quien está en cola no ocupa un puesto de concurrencia hasta que se conecta al agente. #### ¿Quienes llaman pueden escuchar su posición en la cola o un tiempo de espera estimado? Por ahora, no. Quienes están en cola solo escuchan el audio de espera. No se anuncian las posiciones en la cola ni las estimaciones de tiempo de espera. #### ¿Qué ocurre si quien llama cuelga mientras espera? Quien llama sale de la cola inmediatamente y todas las personas detrás avanzan un puesto. No se cobran minutos de conversación. #### ¿La cola de llamadas funciona con llamadas salientes? No. Las llamadas salientes y por lotes solo se realizan cuando hay capacidad disponible, así que nunca se ponen en cola.