Accodamento delle chiamate

Panoramica

Quando un agente o un workspace raggiunge il limite di concorrenza, le nuove chiamate vengono normalmente rifiutate subito. Con l’accodamento delle chiamate attivato, i chiamanti che arrivano mentre l’agente è alla capacità massima restano in linea con l’audio di attesa e vengono connessi automaticamente, nell’ordine di arrivo, non appena si libera uno slot.

L’accodamento delle chiamate viene configurato per ogni agente ed è attivo per impostazione predefinita nei nuovi agenti.

Come funziona l’accodamento delle chiamate

1. Verifica della capacità: quando arriva una chiamata, ElevenAgents verifica se l’agente e il workspace dispongono di uno slot di concorrenza libero. In caso affermativo, la chiamata viene connessa immediatamente.
2. Accodamento: se non è disponibile alcuno slot, il chiamante viene trattenuto nella coda dell’agente e ascolta l’audio di attesa. Non viene avviata alcuna conversazione e non viene addebitato nulla durante l’attesa.
3. Ammissione: non appena si libera uno slot, il chiamante in testa alla coda viene connesso e la conversazione inizia come di consueto.
4. Timeout: se non si libera alcuno slot entro il Tempo massimo di attesa in coda, la chiamata viene disconnessa. Le chiamate telefoniche vengono chiuse normalmente. I client WebSocket ricevono un evento queue_status con stato timed_out, seguito dalla chiusura con codice 4300.

I chiamanti vengono connessi rigorosamente in ordine di arrivo per un determinato agente. Quando più agenti condividono il pool di concorrenza di un workspace, in genere vengono connessi prima i chiamanti che hanno atteso più a lungo.

Cosa sente il chiamante

• I chiamanti telefonici sui numeri Twilio e sui trunk SIP ascoltano l’audio di attesa durante la chiamata.
• Gli utenti del widget e dell’SDK per browser ascoltano l’audio di attesa nel browser. Il widget (versione 0.17.0 o successiva) mostra anche un messaggio di attesa e disabilita l’input di testo durante l’accodamento.
• I client diretti dell’API WebSocket ricevono l’audio di attesa come normali eventi audio, oltre agli eventi queue_status per gestire uno stato di attesa nella tua UI. Consulta Gestione degli eventi della coda.

Fatturazione e durata della conversazione

Il tempo trascorso in coda non viene fatturato, non viene conteggiato nella Durata massima della conversazione dell’agente e non è incluso nella durata riportata per la conversazione. I dettagli della conversazione nella dashboard mostrano per quanto tempo il chiamante ha atteso prima della connessione.

Canali supportati

Configurazione

L’accodamento delle chiamate viene configurato per ogni agente nella sezione Limiti della scheda Sicurezza dell’agente.

I nuovi agenti vengono creati con queueing_config.enabled impostato su true. Per creare un agente con l’accodamento delle chiamate disattivato, imposta queueing_config.enabled su false nella richiesta di creazione.

Gestione dell’audio di attesa tramite API

Carica un file MP3 o WAV per impostare l’audio di attesa personalizzato dell’agente. Il caricamento di un nuovo file sostituisce quello precedente. L’API accetta i tipi di contenuto audio/mpeg e audio/wav, quindi gli esempi impostano esplicitamente il tipo.

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

Rimuovi il clip personalizzato per tornare al tono di attesa predefinito:

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

Il clip attuale viene restituito in sola lettura come platform_settings.queueing_config.hold_audio nell’agente. L’invio di hold_audio in una richiesta di creazione o aggiornamento dell’agente non produce alcun effetto.

Gestione degli eventi della coda in un client WebSocket personalizzato

I client connessi tramite l’API WebSocket ricevono eventi queue_status mentre sono in coda:

{
  "type": "queue_status",
  "queue_status_event": {
    "status": "waiting"
  }
}

• waiting viene inviato una volta, subito dopo conversation_initiation_metadata e prima di qualsiasi audio di attesa.
• admitted viene inviato quando il chiamante viene connesso. La conversazione prosegue quindi come di consueto.
• timed_out viene inviato quando l’attesa supera il tempo massimo di attesa in coda. Il server chiude quindi la connessione con codice 4300.

Le chiamate connesse immediatamente non ricevono mai eventi queue_status. L’evento viene sempre inviato ai chiamanti in coda e non deve essere abilitato in client_events dell’agente.

L’audio di attesa viene fornito come normali eventi audio in blocchi di circa un secondo, a condizione che gli eventi client dell’agente includano audio. Usa queue_status per mostrare uno stato di attesa anziché trattare l’audio di attesa come parlato dell’agente.

FAQ