> 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. # Fila de chamadas ## Visão geral Quando um agente ou workspace atinge o limite de simultaneidade, novas chamadas normalmente são rejeitadas imediatamente. Com a fila de chamadas ativada, os chamadores que chegam enquanto o agente está na capacidade máxima permanecem na linha com áudio de espera e são conectados automaticamente, na ordem em que chegaram, assim que uma vaga é liberada. A fila de chamadas é configurada por agente e vem ativada por padrão para novos agentes. > **Note** > > A fila de chamadas é aplicada quando toda a capacidade disponível está em uso, incluindo a capacidade adicional quando a [cobrança por capacidade adicional](/docs/pt/eleven-agents/guides/burst-pricing) está ativada para o agente. ## Como funciona a fila de chamadas 1. **Verificação de capacidade**: Quando uma chamada chega, o ElevenAgents verifica se o agente e o workspace têm uma vaga de simultaneidade disponível. Se tiverem, a chamada é conectada imediatamente. 2. **Entrada na fila**: Se não houver vaga disponível, o chamador fica na fila do agente e ouve o áudio de espera. Nenhuma conversa é iniciada, e nada é cobrado enquanto o chamador aguarda. 3. **Admissão**: Assim que uma vaga é liberada, o chamador no início da fila é conectado e a conversa começa normalmente. 4. **Tempo limite**: Se nenhuma vaga for liberada dentro do **Tempo máximo de espera na fila**, a chamada será desconectada. Chamadas telefônicas são encerradas normalmente. Clientes WebSocket recebem um evento `queue_status` com o status `timed_out`, seguido do fechamento com o código 4300. Os chamadores são conectados estritamente na ordem de chegada para um determinado agente. Quando vários agentes compartilham o pool de simultaneidade de um workspace, os chamadores que aguardaram mais tempo geralmente são conectados primeiro. ### O que o chamador ouve * Chamadores por telefone em números da Twilio e de tronco SIP ouvem o áudio de espera durante a chamada. * Usuários do widget e do SDK para navegador ouvem o áudio de espera no navegador. O widget (versão 0.17.0 ou posterior) também exibe uma mensagem de espera e desativa a entrada de texto enquanto o usuário está na fila. * Clientes diretos da API WebSocket recebem o áudio de espera como eventos `audio` regulares, além de eventos `queue_status` para controlar um estado de espera na sua própria interface. Consulte [Como lidar com eventos da fila](#handling-queue-events-in-a-custom-websocket-client). ### Cobrança e duração da conversa O tempo passado na fila **não é cobrado**, não conta para a **Duração máxima da conversa** do agente e não é incluído na duração informada da conversa. Os detalhes da conversa no dashboard mostram quanto tempo o chamador aguardou antes de ser conectado. ## Canais compatíveis | Canal | Fila de chamadas | | --------------------------------------------- | ---------------- | | Chamadas recebidas pela Twilio | Compatível | | Chamadas recebidas por tronco SIP | Compatível | | Widget e SDKs de cliente (WebSocket e WebRTC) | Compatível | | API WebSocket direta | Compatível | | Chamadas realizadas e chamadas em lote | Não compatível | | Agentes somente de texto | Não compatível | | Genesys, AudioCodes, Exotel, WhatsApp e SMS | Não compatível | > **Note** > > O limite diário de chamadas não é colocado na fila. Uma chamada que excede o limite diário do agente é rejeitada > imediatamente, pois esse limite só é liberado no dia seguinte. ## Configuração A fila de chamadas é configurada por agente na seção **Limites** da aba **Segurança** do agente. | Configuração | Descrição | Padrão | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------ | | **Ativar fila de chamadas** | Mantém os chamadores em uma fila quando o agente atinge o limite de simultaneidade. | Ativado | | **Tempo máximo de espera na fila** | Por quanto tempo um chamador pode esperar antes de a chamada ser desconectada, em segundos. Entre 1 e 1.800 segundos (30 minutos). | 180 segundos (3 minutos) | | **Áudio de espera personalizado** | Um arquivo MP3 ou WAV reproduzido em loop para os chamadores na fila. Até 40 MB e 3 minutos de duração. Quando nenhum arquivo é enviado, os chamadores ouvem o tom de espera padrão. Envie-o pelo dashboard ou pela API. | Tom de espera padrão | #### Atualizar pelo dashboard #### Abra as configurações de Limites Abra seu agente no dashboard, acesse a aba **Segurança** e role até **Limites**. #### Ative a fila de chamadas Verifique se **Ativar fila de chamadas** está ativado e defina o **Tempo máximo de espera na fila**. #### Envie o áudio de espera (opcional) Em **Áudio de espera personalizado**, envie um arquivo MP3 ou WAV. Você pode ouvir uma prévia do tom de espera padrão e do clipe enviado antes de publicar. #### Publique suas alterações Clique em **Publicar** para aplicar as novas configurações. #### Atualizar pela CLI #### Baixe a configuração do agente ```bash elevenlabs agents pull --agent "" ``` #### Edite \`agent_configs/\.json\` Defina `platform_settings.queueing_config`: ```json { "platform_settings": { "queueing_config": { "enabled": true, "wait_timeout_seconds": 300 } } } ``` #### Envie suas alterações ```bash elevenlabs agents push --agent "" ``` #### Atualizar pela 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, }, }, }); ``` Novos agentes são criados com `queueing_config.enabled` definido como `true`. Para criar um agente com a fila de chamadas desativada, defina `queueing_config.enabled` como `false` na solicitação de criação. ### Gerenciamento do áudio de espera pela API Envie um arquivo MP3 ou WAV para definir o áudio de espera personalizado do agente. O envio de um novo arquivo substitui o anterior. A API aceita os tipos de conteúdo `audio/mpeg` e `audio/wav`, por isso os exemplos definem o tipo explicitamente. ```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, }); ``` Remova o clipe personalizado para voltar ao tom de espera padrão: ```python elevenlabs.conversational_ai.agents.hold_audio.delete( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", ) ``` ```typescript await elevenlabs.conversationalAi.agents.holdAudio.delete("agent_7101k5zvyjhmfg983brhmhkd98n6"); ``` O clipe atual é retornado somente para leitura como `platform_settings.queueing_config.hold_audio` no agente. Enviar `hold_audio` em uma solicitação de criação ou atualização do agente não tem efeito. ## Como lidar com eventos da fila em um cliente WebSocket personalizado Clientes conectados pela [API WebSocket](/docs/pt/eleven-agents/libraries/web-sockets) recebem eventos `queue_status` enquanto estão na fila: ```json { "type": "queue_status", "queue_status_event": { "status": "waiting" } } ``` * `waiting` é enviado uma vez, imediatamente após `conversation_initiation_metadata` e antes de qualquer áudio de espera. * `admitted` é enviado quando o chamador é conectado. A conversa então continua normalmente. * `timed_out` é enviado quando a espera excede o tempo máximo de espera na fila. Em seguida, o servidor fecha a conexão com o código 4300. Chamadas conectadas imediatamente nunca recebem eventos `queue_status`. O evento é sempre enviado aos chamadores na fila e não precisa ser ativado nos `client_events` do agente. O áudio de espera é entregue como eventos `audio` regulares em blocos de aproximadamente um segundo, desde que os eventos de cliente do agente incluam `audio`. Use `queue_status` para mostrar um estado de espera, em vez de tratar o áudio de espera como fala do agente. > **Info** > > Os SDKs `@elevenlabs/client` e `@elevenlabs/react` ainda não oferecem um callback dedicado para esse > evento. Use o callback `onIncomingEvent` para observar eventos brutos do servidor, incluindo > `queue_status`. ## Perguntas frequentes #### Uma chamada na fila conta para meu limite de simultaneidade? Não. Um chamador na fila não ocupa uma vaga de simultaneidade até ser conectado ao agente. #### Os chamadores podem ouvir sua posição na fila ou um tempo de espera estimado? Ainda não. Chamadores na fila ouvem apenas o áudio de espera. A posição na fila e as estimativas de tempo de espera não são informadas. #### O que acontece se o chamador desligar enquanto espera? O chamador sai da fila imediatamente, e todos atrás dele avançam uma posição. Nenhum minuto de conversa é cobrado. #### A fila de chamadas funciona com chamadas realizadas? Não. Chamadas realizadas e em lote são feitas apenas quando há capacidade disponível, portanto nunca entram na fila.