Fila de chamadas

Visão geral

Quando um agente ou workspace atinge seu limite de simultaneidade, novas chamadas normalmente são rejeitadas imediatamente. Com a fila de chamadas ativada, os chamadores que chegarem enquanto o agente estiver sem capacidade permanecem na linha ouvindo o áudio de espera e são conectados automaticamente, na ordem de chegada, assim que uma vaga fica disponível.

A fila de chamadas é configurada por agente e vem desativada por padrão.

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 permanece na fila do agente e ouve o áudio de espera. Nenhuma conversa é iniciada e nada é cobrado enquanto o chamador aguarda.
3. Admissão: no momento em que uma vaga fica disponível, o chamador no início da fila é conectado e a conversa começa normalmente.
4. Tempo limite: se nenhuma vaga ficar disponível dentro do Tempo máximo de espera na fila, a chamada será desconectada. As chamadas telefônicas são encerradas normalmente. Os clientes WebSocket recebem um evento queue_status com o status timed_out, seguido de um encerramento 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 por 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 de fila.

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 painel mostram por quanto tempo o chamador aguardou antes de ser conectado.

Canais compatíveis

Configuração

A fila de chamadas é configurada por agente na seção Limites da aba Segurança do agente.

Como gerenciar o á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, portanto os exemplos definem o tipo explicitamente.

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

Remova o clipe personalizado para voltar ao tom de espera padrão:

elevenlabs.conversational_ai.agents.hold_audio.delete(
    agent_id="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 de agente não tem efeito.

Como lidar com eventos de fila em um cliente WebSocket personalizado

Clientes conectados pela API WebSocket recebem eventos queue_status enquanto estão na fila:

{
  "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. O servidor então fecha a conexão com o código 4300.

Chamadas que se conectam imediatamente nunca recebem eventos queue_status. O evento é sempre enviado aos chamadores na fila e não precisa ser ativado em 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.

Perguntas frequentes