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.

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.

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

Configuração

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

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.

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 do agente não tem efeito.

Como lidar com eventos da 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. 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.

Perguntas frequentes