Integrazione Exotel

Collega i numeri di telefono Exotel a ElevenAgents per le chiamate in entrata e in uscita.

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:

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.
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:

Un account Exotel attivo con almeno un numero di telefono provisionato.
Accesso come amministratore alla dashboard Exotel su my.exotel.com (Singapore) o my.exotel.in (Mumbai).
Un account ElevenLabs e un agente a cui vuoi associare il numero di telefono.

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:

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.
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.

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`

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.

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.

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

Nella dashboard Exotel, apri il menu Manage a sinistra e fai clic su App Bazaar.
Fai clic su Create / Add New Flow, assegna all’app un nome descrittivo (ad es. ElevenLabs), quindi fai clic su OK.
Dalla tavolozza delle applet sulla destra, trascina l’applet Voicebot nell’area di lavoro Call Start.
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
```
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.

(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

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

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`

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.

Salva e pubblica l’applet.
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.

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.

Nella dashboard Exotel, apri il menu Manage a sinistra e fai clic su ExoPhones (subito sotto App Bazaar).
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.
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).
Salva la configurazione. Le chiamate in arrivo a quel numero verranno ora instradate direttamente nell’applet Voicebot e trasmesse a ElevenLabs.

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. Fai clic su + Import number e seleziona From Exotel dal menu a discesa.

ElevenAgents: menu a discesa Import number con From Exotel
selezionato

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.

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.

Monitora la chiamata nella dashboard Calls 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, individua il tuo numero Exotel e fai clic sul pulsante Outbound call.

Configura la chiamata

Nella finestra modale Outbound Call:

Seleziona l’agente che gestirà la conversazione.
Inserisci il numero di telefono del destinatario in formato E.164.
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.

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. 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:

L’applet Connect facoltativa configurata immediatamente dopo l’applet Voicebot nel tuo flusso ExoML (vedi il passaggio 5 in Configurazione su Exotel).
Lo strumento Transfer to number configurato sul tuo agente. Consulta la guida al trasferimento dell’agente.

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.