> 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. # 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. > **Note** > > L'accodamento delle chiamate si applica una volta utilizzata tutta la capacità disponibile, inclusa la capacità burst quando per l'agente è attivata la [tariffazione burst](/docs/it/eleven-agents/guides/burst-pricing). ## 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](#handling-queue-events-in-a-custom-websocket-client). ### 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 | Canale | Accodamento chiamate | | ------------------------------------------- | -------------------- | | Chiamate in entrata Twilio | Supportato | | Chiamate in entrata su trunk SIP | Supportato | | Widget e SDK client (WebSocket e WebRTC) | Supportato | | API WebSocket diretta | Supportato | | Chiamate in uscita e chiamate batch | Non supportato | | Agenti solo testo | Non supportato | | Genesys, AudioCodes, Exotel, WhatsApp e SMS | Non supportato | > **Note** > > Il limite giornaliero di chiamate non viene accodato. Una chiamata che supera il limite giornaliero > dell'agente viene rifiutata immediatamente, perché tale limite non si libera fino al giorno successivo. ## Configurazione L'accodamento delle chiamate viene configurato per ogni agente nella sezione **Limiti** della scheda **Sicurezza** dell'agente. | Impostazione | Descrizione | Predefinito | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | | **Abilita accodamento chiamate** | Mantieni i chiamanti in coda quando l'agente raggiunge il limite di concorrenza. | Attivo | | **Tempo massimo di attesa in coda** | Quanto tempo può attendere un chiamante prima che la chiamata venga disconnessa, in secondi. Da 1 a 1.800 secondi (30 minuti). | 180 secondi (3 minuti) | | **Audio di attesa personalizzato** | Un file MP3 o WAV riprodotto in loop per i chiamanti in coda. Fino a 40 MB e 3 minuti di durata. Se non viene caricato alcun file, i chiamanti ascoltano il tono di attesa predefinito. Caricalo nella dashboard o tramite API. | Tono di attesa predefinito | #### Aggiorna dalla dashboard #### Apri le impostazioni dei limiti Apri il tuo agente nella dashboard, vai alla scheda **Sicurezza** e scorri fino a **Limiti**. #### Abilita l'accodamento delle chiamate Assicurati che **Abilita accodamento chiamate** sia attivo e imposta il **Tempo massimo di attesa in coda**. #### Carica l'audio di attesa (facoltativo) In **Audio di attesa personalizzato**, carica un file MP3 o WAV. Puoi ascoltare in anteprima il tono di attesa predefinito e il clip caricato prima della pubblicazione. #### Pubblica le modifiche Fai clic su **Pubblica** per applicare le nuove impostazioni. #### Aggiorna tramite CLI #### Scarica la configurazione dell'agente ```bash elevenlabs agents pull --agent "" ``` #### Modifica \`agent\_configs/\.json\` Imposta `platform_settings.queueing_config`: ```json { "platform_settings": { "queueing_config": { "enabled": true, "wait_timeout_seconds": 300 } } } ``` #### Invia le modifiche ```bash elevenlabs agents push --agent "" ``` #### Aggiorna tramite 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, }, }, }); ``` 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. ```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, }); ``` Rimuovi il clip personalizzato per tornare al tono di attesa predefinito: ```python elevenlabs.conversational_ai.agents.hold_audio.delete( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", ) ``` ```typescript await elevenlabs.conversationalAi.agents.holdAudio.delete("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](/docs/it/eleven-agents/libraries/web-sockets) ricevono eventi `queue_status` mentre sono in coda: ```json { "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. > **Info** > > Gli SDK `@elevenlabs/client` e `@elevenlabs/react` non espongono ancora un callback dedicato per questo > evento. Usa il callback `onIncomingEvent` per osservare gli eventi raw del server, incluso > `queue_status`. ## FAQ #### Una chiamata in coda viene conteggiata nel mio limite di concorrenza? No. Un chiamante in coda non occupa uno slot di concorrenza finché non viene connesso all'agente. #### I chiamanti possono sentire la loro posizione in coda o un tempo di attesa stimato? Al momento no. I chiamanti in coda ascoltano solo l'audio di attesa. La posizione in coda e le stime dei tempi di attesa non vengono annunciate. #### Cosa succede se il chiamante riaggancia durante l'attesa? Il chiamante esce subito dalla coda e tutti quelli dietro avanzano di una posizione. Non vengono addebitati minuti di conversazione. #### L'accodamento delle chiamate funziona con le chiamate in uscita? No. Le chiamate in uscita e batch vengono effettuate solo quando è disponibile capacità, quindi non vengono mai accodate.