> 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. # Five9 > **Note** > > Prima di seguire questa guida, ti consigliamo di leggere la [guida al SIP trunking ](/docs/it/eleven-agents/phone-numbers/sip-trunking) per capire come ElevenLabs supporta i trunk SIP > e gli header SIP personalizzati. ## Panoramica Questa guida spiega come integrare ElevenAgents con il Virtual Contact Center (VCC) di Five9 tramite Five9 AI Agent Connect. Five9 trasferisce una chiamata in corso a un numero di telefono ElevenLabs, l'agente ElevenLabs gestisce la conversazione e ElevenLabs restituisce a Five9 dati di instradamento o di esito affinché il flusso Five9 possa continuare. ## Come funziona l'integrazione Five9 Five9 AI Agent Connect utilizza un trasferimento esterno tramite SIP, con il contesto della chiamata scambiato tramite header SIP `X-` personalizzati in entrambe le direzioni: 1. **Trasferimento in entrata**: il modulo External Transfer IVR di Five9 trasferisce la chiamata a un numero di telefono ElevenLabs, inviando il contesto della chiamata come header SIP `X-` nell'INVITE. 2. **Conversazione**: ElevenLabs risponde alla chiamata e la instrada all'agente corretto, facoltativamente tramite un agente router, quindi gestisce la conversazione con il chiamante. 3. **Percorso di ritorno**: al termine della conversazione, ElevenLabs aggiunge dati di instradamento e di esito al SIP BYE come header `X-`. 4. **Instradamento post-IA**: Five9 mappa gli header restituiti nelle variabili di chiamata e prosegue il flusso, ad esempio trasferendo a un operatore umano, terminando la chiamata o registrando un esito. ## Requisiti Prima di configurare l'integrazione Five9, assicurati di disporre di: 1. Un dominio Five9 VCC attivo con AI Agent Connect abilitato. 2. Accesso amministratore alla configurazione Five9 oppure di un team di implementazione Five9 che possa apportare le modifiche. 3. Un account ElevenLabs e un [agente](/docs/it/eleven-agents/quickstart) per gestire le chiamate trasferite. 4. Un [numero di telefono con trunk SIP](/docs/it/eleven-agents/phone-numbers/sip-trunking) importato in ElevenLabs da utilizzare come destinazione del trasferimento Five9. > **Note** > > AI Agent Connect è un componente aggiuntivo a pagamento di Five9 VCC e non è abilitato per impostazione predefinita. Contatta il tuo Account Manager Five9 per abilitarlo per il tuo dominio prima di avviare questa integrazione. > **Note** > > Prima di iniziare la configurazione, entrambi i team devono concordare il numero di telefono per il trasferimento, i nomi degli header inviati in ciascuna direzione, i valori di instradamento e il piano di test. ## Configurazione di ElevenLabs #### Importa il numero di telefono per il trasferimento Segui la [guida al SIP trunking](/docs/it/eleven-agents/phone-numbers/sip-trunking) per importare il numero di telefono a cui Five9 trasferirà le chiamate. Gli header SIP personalizzati e gli header BYE richiedono un numero di telefono con trunk SIP. Importa il numero in formato E.164 con prefisso internazionale `+1` (ad esempio, `+18005550100`). Five9 invia il trasferimento in questo formato e una mancata corrispondenza causerà l'errore del trasferimento. #### Assegna un agente Se un singolo agente gestisce tutte le chiamate da Five9, assegnalo direttamente al numero di telefono nella [dashboard Numeri di telefono](https://elevenlabs.io/app/agents/phone-numbers). Se più agenti condividono un numero di trasferimento, assegna invece un agente router e segui [Instradare più agenti tramite un unico numero](#routing-multiple-agents-through-one-number). #### Configura gli header restituiti Mappa le variabili dinamiche impostate dall'agente durante la conversazione ai nomi degli header SIP BYE previsti da Five9. Consulta [Configurare gli header BYE](#configuring-bye-headers). #### Esegui chiamate di test Effettua chiamate di test con Five9 e verifica che gli header in entrata arrivino come variabili dinamiche e che gli header BYE vengano restituiti come previsto. I valori degli header in entrata sono visibili nella cronologia della conversazione nella scheda **Phone Call**. ## Instradare più agenti tramite un unico numero Per instradare chiamate a più agenti ElevenLabs tramite un singolo numero di trasferimento Five9, assegna un **agente router** al numero di telefono e fai in modo che Five9 invii l'agente di destinazione in un header come `X-AgentID`. Gli header `X-` in entrata sono esposti come [variabili dinamiche](/docs/it/eleven-agents/customization/personalization/dynamic-variables), quindi `X-AgentID` è disponibile per l'agente router come `{{sip_agentid}}`. Configura l'agente router con lo strumento [trasferimento dell'agente](/docs/it/eleven-agents/customization/tools/system-tools/agent-transfer) e aggiungi una regola di trasferimento per ogni valore `X-AgentID` previsto, mappandolo all'agente che deve gestire la chiamata. Così eviti di configurare un numero di telefono separato per ogni agente. ## Header inviati da Five9 a ElevenLabs Five9 può inviare metadati della chiamata come header SIP `X-` nell'INVITE. I nomi degli header vengono normalizzati rimuovendo il prefisso `X-`, convertendoli in minuscolo, sostituendo i trattini con trattini bassi e aggiungendo il prefisso `sip_`. | Header | Variabile dinamica | Descrizione | | ----------------- | ----------------------- | -------------------------------------------------------------------------------------- | | `X-CallANI` | `{{sip_callani}}` | Il numero di telefono del chiamante. | | `X-CallDNIS` | `{{sip_calldnis}}` | Il numero di telefono chiamato. | | `X-CallID` | `{{sip_callid}}` | Identificatore univoco della chiamata Five9. | | `X-CallSessionID` | `{{sip_callsessionid}}` | Identificatore della sessione corrente. | | `X-CallCampaign` | `{{sip_callcampaign}}` | Nome della campagna Five9. | | `X-AgentID` | `{{sip_agentid}}` | Agente ElevenLabs di destinazione, usato per l'instradamento tramite un agente router. | Usa queste variabili nei prompt dell'agente, nei primi messaggi e negli strumenti per personalizzare la conversazione. > **Note** > > Gli header riservati `X-Call-ID` e `X-Caller-ID` vengono mappati alle [variabili dinamiche di sistema ](/docs/it/eleven-agents/customization/personalization/dynamic-variables#system-dynamic-variables) `system__call_sid` e > `system__caller_id`. > Five9 invia `X-CallID` e `X-CallANI` senza trattini, che vengono invece normalizzati in `sip_callid` e > `sip_callani`. Prima di usarle nei prompt, verifica quali variabili vengono popolate durante le chiamate di test. ## Header restituiti da ElevenLabs a Five9 ElevenLabs restituisce dati di instradamento e di report nel SIP BYE. I seguenti nomi di header sono la convenzione consigliata per Five9 AI Agent Connect: | Header | Descrizione | | ------------------ | ----------------------------------------------------------------------------- | | `X-RouteType` | L'azione che Five9 deve eseguire, ad esempio `SkillTransfer`. | | `X-RouteValue` | La destinazione dell'azione, ad esempio il nome di una skill Five9. | | `X-RouteReason` | Contesto della decisione di instradamento, come l'intento del cliente. | | `X-ConversationId` | L'identificatore della conversazione ElevenLabs, per la correlazione dei log. | Puoi restituire qualsiasi header `X-` aggiuntivo necessario al tuo flusso Five9. Il valore di ciascun header proviene da una variabile dinamica dell'agente, quindi l'agente deve impostare queste variabili durante la conversazione. ## Configurare gli header BYE Gli header BYE restituiscono a Five9 i valori finali delle variabili dinamiche dell'agente. Mappa ciascun nome di variabile dinamica a un nome di header usando `attributes_to_headers` in `inbound_trunk_config` del numero di telefono. Puoi mappare sia le variabili impostate dall'agente sia le [variabili dinamiche di sistema](/docs/it/eleven-agents/customization/personalization/dynamic-variables#system-dynamic-variables), come `system__conversation_id`: **`Python`** ```python title="Python" import os from dotenv import load_dotenv from elevenlabs import ElevenLabs, InboundSipTrunkConfigRequestModel load_dotenv() elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY")) elevenlabs.conversational_ai.phone_numbers.update( phone_number_id="phnum_8901k4t9z5defmb8vh3e9361y7nj", inbound_trunk_config=InboundSipTrunkConfigRequestModel( attributes_to_headers={ "route_type": "X-RouteType", "route_value": "X-RouteValue", "route_reason": "X-RouteReason", "system__conversation_id": "X-ConversationId", } ), ) ``` **`JavaScript`** ```typescript title="JavaScript" import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); await elevenlabs.conversationalAi.phoneNumbers.update("phnum_8901k4t9z5defmb8vh3e9361y7nj", { inboundTrunkConfig: { attributesToHeaders: { route_type: "X-RouteType", route_value: "X-RouteValue", route_reason: "X-RouteReason", system__conversation_id: "X-ConversationId", }, }, }); ``` **`cURL`** ```bash title="cURL" curl -X PATCH "https://api.elevenlabs.io/v1/convai/phone-numbers/phnum_8901k4t9z5defmb8vh3e9361y7nj" \ -H "xi-api-key: $ELEVENLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "inbound_trunk_config": { "attributes_to_headers": { "route_type": "X-RouteType", "route_value": "X-RouteValue", "route_reason": "X-RouteReason", "system__conversation_id": "X-ConversationId" } } }' ``` Il valore dell'header è il valore della variabile dinamica al termine della conversazione, inclusi i valori impostati durante la chiamata tramite strumenti dell'agente o override del webhook. Una chiamata che termina con l'agente che imposta `route_type` su `SkillTransfer` e `route_value` su `billing_support` produce i seguenti header BYE: ``` X-RouteType: SkillTransfer X-RouteValue: billing_support X-RouteReason: Customer needs help with an invoice X-ConversationId: conv_7401k6a2b8cxyzmn9pq3r5s7t1uv ``` Five9 instrada quindi il chiamante alla skill `billing_support`. ## Valori di instradamento consigliati Mantieni i valori di `X-RouteType` semplici e prevedibili, così il flusso Five9 può creare diramazioni direttamente in base a essi. | `X-RouteType` | Esempio di `X-RouteValue` | Descrizione | | ----------------- | ------------------------- | --------------------------------------------------------- | | `SkillTransfer` | `billing_support` | Trasferisce la chiamata a una specifica coda skill Five9. | | `PhoneTransfer` | `+18005550199` | Trasferisce la chiamata a un numero di telefono esterno. | | `Hangup` | Vuoto | Termina la chiamata dopo l'interazione con l'IA. | | `DispositionOnly` | `Resolved` | Termina la chiamata e registra un esito specifico. | ## Configurazione di Five9 Il tuo team di implementazione Five9 in genere: 1. Abilita AI Agent Connect per il tuo dominio Five9. 2. Configura il flusso di trasferimento IVR di Five9. 3. Aggiunge il numero di telefono ElevenLabs come destinazione del trasferimento. 4. Configura il modulo External Transfer. 5. Configura gli header `X-` in uscita inviati a ElevenLabs. 6. Configura gli header `X-` in entrata restituiti da ElevenLabs. 7. Mappa gli header restituiti nelle variabili di chiamata Five9. 8. Configura la logica di instradamento post-IA che crea diramazioni in base a tali variabili. 9. Testa le chiamate end-to-end. ## Risoluzione dei problemi #### Le chiamate trasferite non riescono a connettersi * Verifica che il numero di telefono ElevenLabs sia importato come numero con trunk SIP e che gli sia assegnato un agente. * Verifica che la destinazione del trasferimento configurata nel modulo External Transfer di Five9 corrisponda al numero importato. * Controlla che il firewall consenta il traffico di segnalazione SIP sul trasporto e sulla porta configurati e che le porte RTP non siano bloccate. #### Gli header in entrata non sono disponibili come variabili dinamiche * Verifica che Five9 invii gli header con un prefisso `X-` nell'INVITE. * Controlla il nome della variabile normalizzato. `X-AgentID` diventa `{{sip_agentid}}`, non `{{X-AgentID}}` né `{{agent_id}}`. * Esamina la cronologia della conversazione nella scheda **Phone Call** per vedere quali header sono arrivati. * Gli header personalizzati non possono sovrascrivere le variabili di sistema `system__call_sid` e `system__caller_id`. #### Gli header BYE sono mancanti o vuoti * Verifica che `attributes_to_headers` sia impostato in `inbound_trunk_config` per il numero di telefono che riceve la chiamata. * Verifica che le chiavi siano nomi di variabili dinamiche e i valori siano nomi di header, non il contrario. * Assicurati che l'agente imposti effettivamente tali variabili dinamiche durante la conversazione. Una variabile non impostata non produce alcun valore dell'header. #### L'agente router trasferisce al agente sbagliato * Verifica che Five9 invii `X-AgentID` a ogni chiamata trasferita. * Controlla che ogni valore `X-AgentID` disponga di una regola di trasferimento corrispondente nell'agente router. * Verifica che le regole di trasferimento dell'agente router facciano riferimento a `{{sip_agentid}}`. ## Link utili * [Guida al SIP trunking](/docs/it/eleven-agents/phone-numbers/sip-trunking) * [Riferimento SIP](/docs/it/eleven-agents/phone-numbers/sip-reference) * [Strumento di trasferimento dell'agente](/docs/it/eleven-agents/customization/tools/system-tools/agent-transfer) * [Variabili dinamiche](/docs/it/eleven-agents/customization/personalization/dynamic-variables) * [Riferimento API per l'aggiornamento del numero di telefono](/docs/it/api-reference/phone-numbers/update)