> 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. # Integrazione Exotel ## Panoramica Questa guida spiega come collegare direttamente i tuoi numeri di telefono Exotel a ElevenAgents. Questa integrazione ti consente di usare i numeri e l'infrastruttura Exotel esistenti sfruttando le funzionalità avanzate di IA vocale di ElevenLabs, sia per le chiamate in entrata sia per quelle in uscita. ## Come funziona l'integrazione L'integrazione con Exotel usa due componenti Exotel: 1. **Applet Voicebot (contenuti multimediali in entrata e in uscita)**: un'applet ExoML su Exotel che apre un WebSocket verso ElevenLabs e trasmette l'audio della chiamata in entrambe le direzioni. 2. **API Connect (composizione in uscita)**: per le chiamate in uscita, ElevenLabs chiama l'endpoint `Calls/connect.json` di Exotel usando la tua API Key e il tuo API Token. Exotel chiama il destinatario e, quando risponde, instrada l'audio attraverso la stessa applet Voicebot verso ElevenLabs. Per le chiamate **in entrata**, Exotel instrada le chiamate in arrivo all'applet Voicebot assegnata al numero di telefono, che apre il WebSocket verso ElevenLabs. Per le chiamate **in uscita**, ElevenLabs avvia la chiamata tramite l'API Connect e Exotel la collega nuovamente attraverso l'applet Voicebot. ## Requisiti Prima di configurare l'integrazione con Exotel, assicurati di avere: 1. Un [account Exotel](https://exotel.com/) attivo con almeno un numero di telefono provisionato. 2. Accesso come amministratore alla dashboard Exotel su [my.exotel.com](https://my.exotel.com) (Singapore) o [my.exotel.in](https://my.exotel.in) (Mumbai). 3. Un account ElevenLabs e un [agente](/docs/it/eleven-agents/quickstart) a cui vuoi associare il numero di telefono. > **Note** > > Exotel è attualmente supportato sui cluster **Singapore** (`api.exotel.com`) e **Mumbai** > (`api.in.exotel.com`). Scegli il cluster in cui è stato provisionato il tuo account Exotel. L'uso della > regione errata causerà errori di autenticazione. ## Abilitare Voicebot sul tuo account Exotel Prima di tutto, contatta l'**assistenza Exotel** e chiedi di: 1. **Abilitare l'applet Voicebot** sul tuo account. Per impostazione predefinita è soggetta ad autorizzazione e non apparirà nell'App Bazaar finché il tuo account non sarà stato provisionato per usarla. 2. **Provisionare il numero di canali (chiamate simultanee)** di cui hai bisogno. Questo è il limite di chiamate Voicebot simultanee che Exotel consentirà al tuo account di gestire. Dimensiona il servizio in base al picco di traffico previsto. > **Warning** > > Questo passaggio richiede in genere da 1 a 2 giorni lavorativi. Avvialo prima di iniziare il resto della configurazione. ## Endpoint WebSocket di ElevenLabs Configurerai l'applet Voicebot di Exotel per trasmettere l'audio al seguente URL WebSocket. | Ambiente | URL WebSocket | | -------------------------------- | -------------------------------------------------------------------- | | Predefinito (USA/Internazionale) | `wss://api.elevenlabs.io/v1/convai/conversation/exotel` | | Residenza UE | `wss://api.eu.residency.elevenlabs.io/v1/convai/conversation/exotel` | | Residenza in India | `wss://api.in.residency.elevenlabs.io/v1/convai/conversation/exotel` | > **Info** > > Se il tuo account ElevenLabs si trova in un ambiente di residenza isolato (UE o India), devi usare il > corrispondente URL di residenza. Scopri di più sulla [residenza dei dati](/docs/it/overview/administration/data-residency). ## Configurazione su Exotel #### Recupera le tue credenziali Exotel Nella dashboard Exotel, apri il menu **Monitor** a sinistra e fai clic su **Developer**. Si aprirà la pagina delle credenziali API, dove puoi consultare Account SID, API Key e API Token. ![Barra laterale Exotel: Developer](/docs/_fern-img/ebe936f8cd0d1773a88bb4922a7642cf8c2f844f39eb4ee9ee04eab50ecfa6c4.webp) Ti serviranno quattro valori: * **Account SID**: l'SID del tuo account Exotel. * **API Key**: la parte relativa al nome utente delle credenziali API Exotel. * **API Token**: la parte relativa alla password delle credenziali API Exotel. Mantienilo segreto. * **Regione (sottodominio API)**: il cluster in cui si trova il tuo account Exotel. Può essere `api.exotel.com` (Singapore) o `api.in.exotel.com` (Mumbai). Puoi verificare quale sia controllando l'host di uno qualsiasi degli URL API mostrati nella pagina Developer. ElevenLabs usa API Key + API Token per l'autenticazione HTTP Basic quando chiama l'API Connect di Exotel per la composizione in uscita. #### Crea un'applet Voicebot nell'App Bazaar 1. Nella dashboard Exotel, apri il menu **Manage** a sinistra e fai clic su **App Bazaar**. ![Barra laterale Exotel: App Bazaar](/docs/_fern-img/1e50c6687044e4fea1e6e636bc2db8a4a481c87eb44cdfc8019cff20bd1fe363.webp) 2. Fai clic su **Create / Add New Flow**, assegna all'app un nome descrittivo (ad es. `ElevenLabs`), quindi fai clic su **OK**. ![Exotel: finestra di dialogo Add New Flow](/docs/_fern-img/928f17d1351f93e7a9bd60d92498dde8b24d350686cf273be146e9d315927704.webp) 3. Dalla tavolozza delle applet sulla destra, trascina l'applet **Voicebot** nell'area di lavoro **Call Start**. ![Tavolozza delle applet Exotel con Voicebot evidenziato](/docs/_fern-img/d19a0e66925d5931cd8f9eae7a1264b8a0e259d07736564cab4e1e894401c508.webp) 4. Apri la configurazione dell'applet Voicebot e incolla nel campo **URL** (il campo "Which bot you want to connect the enduser?") l'URL WebSocket di ElevenLabs per la tua residenza: ``` wss://api.elevenlabs.io/v1/convai/conversation/exotel ``` > **Info** > > Se il tuo account ElevenLabs utilizza la residenza UE o India, usa l'URL di residenza corrispondente dalla > tabella sopra (ad es. `wss://api.in.residency.elevenlabs.io/v1/convai/conversation/exotel`) anziché > quello predefinito `api.elevenlabs.io`. Le altre opzioni di Voicebot ("Record this?", "Recording Channels", "Recording Format", "Encrypt DTMF") possono rimanere sui valori predefiniti, a meno che tu non abbia esigenze specifiche di registrazione o conformità normativa. ![Applet Voicebot configurata con l'URL WebSocket di ElevenLabs ](/docs/_fern-img/bb375863bb02b0908786403c080280f4561f21d887fb490050d54ff4ec211794.webp) 5. **(Facoltativo) Collega un'applet Connect per i trasferimenti a operatori umani.** Salta questo passaggio se non hai bisogno che l'agente possa trasferire la chiamata a una persona. Se vuoi usare lo strumento **Transfer to number** dell'agente, devi aggiungere un'applet **Connect** immediatamente dopo l'applet Voicebot nel flusso. Dalla tavolozza **Voice Applets** sulla destra, trascina l'applet **Connect** nello slot **Next → Continue to the next applet** di Voicebot. ![Tavolozza Voice Applets con Connect evidenziato](/docs/_fern-img/1c325fc4ae992db551209b667519ffd75161b6a97ebf71ed6b751bbf26339faf.webp) Nella configurazione dell'applet Connect, scegli **Configure parameters dynamically by providing a URL** e incolla nell'**Primary URL** l'endpoint dell'applet Connect di ElevenLabs per la tua residenza: ``` https://api.elevenlabs.io/v1/convai/exotel/connect-applet ``` ![Applet Connect configurata con l'URL dinamico di ElevenLabs ](/docs/_fern-img/7ed4516ec33ea62830d9279a266ada20311741d0489fe2661dc528b8dbcbe126.webp) Gli URL di residenza corrispondenti sono: | Ambiente | URL dell'applet Connect | | -------------------------------- | ------------------------------------------------------------------------ | | Predefinito (USA/Internazionale) | `https://api.elevenlabs.io/v1/convai/exotel/connect-applet` | | Residenza UE | `https://api.eu.residency.elevenlabs.io/v1/convai/exotel/connect-applet` | | Residenza in India | `https://api.in.residency.elevenlabs.io/v1/convai/exotel/connect-applet` | > **Info** > > Quando l'agente richiama lo strumento **Transfer to number**, ElevenLabs restituisce il controllo a Exotel > ed Exotel recupera questo URL per ottenere il numero di destinazione da chiamare. Lascia vuoto il campo **Fallback URL** > e mantieni tutti gli altri valori predefiniti. 6. Salva e pubblica l'applet. 7. Annota l'**Applet ID** (talvolta chiamato **App ID**). Lo trovi nell'URL dell'editor ExoML (ad es. `.../exoml/start_voice/12345`) o nell'elenco delle app. Ti servirà quando importerai il numero in ElevenLabs. > **Note** > > L'applet Voicebot gestisce sia le parti in entrata sia quelle in uscita. Ti serve una sola applet per > account. Tutti i numeri di telefono importati in ElevenLabs possono condividerla. #### Assegna il flusso a un numero di telefono (solo chiamate in entrata) Salva e pubblica il flusso ExoML del passaggio precedente. Quindi instrada un numero di telefono Exotel verso di esso, affinché le chiamate in entrata arrivino all'applet Voicebot. 1. Nella dashboard Exotel, apri il menu **Manage** a sinistra e fai clic su **ExoPhones** (subito sotto **App Bazaar**). ![Barra laterale Exotel: ExoPhones](/docs/_fern-img/30351173b2c2cfaa2ccd8d9e29e6aaba319ac3b5f2ee51d91a4f7913d3e218a4.webp) 2. Se non hai già un numero di telefono, fai clic su **Buy a number** e acquistane uno nel paese o nell'area che ti serve prima di continuare. 3. Trova il numero che vuoi usare con il tuo agente ElevenLabs. Nella relativa colonna **Installed App**, apri il menu a discesa e seleziona il flusso creato nel passaggio precedente (ad es. **ElevenLabs**). ![ExoPhones: assegna Installed App a un numero di telefono ](/docs/_fern-img/5ed6b42794bb00f330dd52d50a5831622e3156955d59adb1ca64b746d1ec7d2b.webp) 4. Salva la configurazione. Le chiamate in arrivo a quel numero verranno ora instradate direttamente nell'applet Voicebot e trasmesse a ElevenLabs. > **Note** > > Se il numero verrà usato solo per chiamate in uscita, puoi saltare questo passaggio. Le chiamate in uscita vengono > effettuate tramite l'API Connect da ElevenLabs e non dipendono dall'assegnazione di **Installed App**. ## Configurazione su ElevenLabs #### Importa il numero di telefono Exotel Nella dashboard ElevenAgents, vai alla scheda [**Phone Numbers**](https://elevenlabs.io/app/agents/phone-numbers). Fai clic su **+ Import number** e seleziona **From Exotel** dal menu a discesa. ![ElevenAgents: menu a discesa Import number con From Exotel selezionato](/docs/_fern-img/2a62cf9f6b63914c5688da5f58515168fa1ff39b8602f70fea7a1ff257bb6918.webp) Compila i seguenti campi: * **Label**: un nome descrittivo (ad es. `Support Line`). * **Phone number**: il numero Exotel in formato E.164 (ad es. `+918048961234`). * **Exotel Account SID**: dal passaggio 1 sopra. * **Exotel API Key**: dal passaggio 1 sopra. * **Exotel API Token**: dal passaggio 1 sopra (archiviato come segreto del workspace). * **Region**: seleziona `Singapore (api.exotel.com)` o `Mumbai (api.in.exotel.com)` in base al tuo cluster Exotel. * **Voicebot Applet ID**: l'App ID dal passaggio 2 sopra. Fai clic su **Import** per salvare il numero. ElevenLabs verificherà le credenziali con Exotel e memorizzerà l'API token come segreto del workspace. #### Assegna il tuo agente Dopo aver importato il numero, aprilo dall'elenco **Phone Numbers** e seleziona nel menu a discesa **Assigned agent** l'agente che dovrà gestire le chiamate in entrata. > **Note** > > Le chiamate in entrata richiedono che l'applet Voicebot sia assegnata al numero lato Exotel (vedi la > sezione precedente). Le configurazioni solo per chiamate in uscita non richiedono un'assegnazione per le chiamate in entrata. #### Prova una chiamata in entrata Chiama il tuo numero Exotel da qualsiasi telefono. Exotel instraderà la chiamata all'applet Voicebot, che apre un WebSocket verso ElevenLabs. Il tuo agente risponderà e inizierà la conversazione. > **Tip** > > Monitora la chiamata nella [dashboard Calls History](https://elevenlabs.io/app/agents/history) per > verificare che tutto funzioni come previsto. ## Effettuare chiamate in uscita I numeri Exotel importati possono anche avviare chiamate in uscita. Il tuo agente chiama un numero di telefono e avvia la conversazione quando il destinatario risponde. #### Avvia una chiamata in uscita Dalla scheda [**Phone Numbers**](https://elevenlabs.io/app/agents/phone-numbers), individua il tuo numero Exotel e fai clic sul pulsante **Outbound call**. #### Configura la chiamata Nella finestra modale Outbound Call: 1. Seleziona l'agente che gestirà la conversazione. 2. Inserisci il numero di telefono del destinatario in formato E.164. 3. Fai clic su **Send Test Call** per avviare la chiamata. ElevenLabs chiama l'API Connect di Exotel con le credenziali archiviate. Exotel chiama il destinatario e instrada l'audio attraverso l'applet Voicebot quando la chiamata riceve risposta. > **Note** > > Quando effettui chiamate in uscita, il tuo agente avvia la conversazione, quindi assicurati che abbia > configurato un messaggio iniziale appropriato. Per attivare chiamate in uscita a livello programmatico anziché dalla dashboard, usa l'endpoint [Outbound call via Exotel](/docs/it/api-reference/exotel/outbound-call). Il riferimento API include lo schema della richiesta e snippet SDK pronti all'uso. ## Requisiti di configurazione dell'agente L'applet Voicebot trasmette audio a **8 kHz PCM**. La piattaforma ElevenLabs gestisce automaticamente la conversione del formato audio. **Non** devi modificare le impostazioni TTS o dell'audio in ingresso dell'agente. ## Formati dei numeri di telefono I numeri di telefono vengono memorizzati in formato E.164 (ad es. `+918048961234`). Quando importi un numero Exotel indiano che potresti scrivere localmente come `08048961234` o `8048961234`, inseriscilo come `+918048961234`. ElevenLabs rifiuterà le importazioni duplicate dello stesso numero in formati diversi. ## Trasferimenti di chiamata Puoi trasferire le chiamate dal tuo agente a Exotel configurando uno strumento **Transfer to number** sul tuo agente. Quando lo strumento viene attivato, ElevenLabs termina la parte Voicebot ed Exotel recupera il numero di destinazione dall'URL dinamico dell'applet **Connect** collegata, quindi effettua la chiamata. Affinché funzioni, ti servono **entrambi**: 1. L'applet **Connect** facoltativa configurata immediatamente dopo l'applet Voicebot nel tuo flusso ExoML (vedi il passaggio 5 in [Configurazione su Exotel](#setup-on-exotel)). 2. Lo strumento **Transfer to number** configurato sul tuo agente. Consulta la [guida al trasferimento dell'agente](/docs/it/eleven-agents/customization/tools/system-tools/transfer-to-number). Senza l'applet Connect nel flusso, i tentativi di trasferimento dell'agente non riusciranno perché Exotel non avrà dove instradare la chiamata dopo la fine di Voicebot. ## Risoluzione dei problemi #### Errore \`exotel\_connect\_failed\` all'avvio di una chiamata in uscita ElevenLabs ha ricevuto una risposta diversa da 200 dall'API Connect di Exotel. Le cause più comuni sono: * **Regione** errata. Assicurati che la regione selezionata al momento dell'importazione corrisponda al cluster Exotel in cui si trova il tuo account (`Singapore` o `Mumbai`). * **API Key** o **API Token** non validi. Ricontrolla le credenziali nella pagina **API Settings** di Exotel e importa nuovamente il numero con i valori corretti. * L'**Account SID** non corrisponde alla coppia API Key / Token. * Il numero di destinazione non è in formato E.164. #### Le chiamate in entrata non raggiungono il mio agente * Verifica che il campo **URL** dell'applet Voicebot corrisponda esattamente all'endpoint WebSocket ElevenLabs per la tua residenza dei dati (incluso `wss://`). * Verifica che il **numero di telefono** Exotel sia instradato verso l'app ExoML contenente l'applet Voicebot (dashboard Exotel, ExoPhones, numero, Installed App). * In ElevenLabs, verifica che al numero di telefono sia assegnato un agente nella scheda **Phone Numbers**. #### Errori di mancata corrispondenza di \`Applet ID\` durante l'importazione Il campo **Voicebot Applet ID** richiede l'App ID numerico dall'URL dell'editor ExoML (ad es. per `.../exoml/start_voice/12345`, l'ID è `12345`). Non incollare l'URL completo. Usa solo l'ID. #### Numero di telefono importato due volte in formati diversi ElevenLabs normalizza i numeri Exotel in formato E.164 prima di memorizzarli e impone l'univocità su `(provider, phone_number)`. Se in precedenza hai importato lo stesso numero in un formato diverso da E.164, elimina prima la vecchia voce e poi importalo nuovamente in formato E.164. ## Link utili * [Riferimento API per le chiamate in uscita via Exotel](/docs/it/api-reference/exotel/outbound-call) * [Documentazione API Exotel](https://developer.exotel.com/api/) * [Riferimento dell'applet Voicebot Exotel](https://support.exotel.com/support/solutions/articles/3000099826) * [Dashboard dei numeri di telefono ElevenAgents](https://elevenlabs.io/app/agents/phone-numbers)