SIP trunking

Panoramica

Il SIP trunking (Session Initiation Protocol) ti consente di collegare direttamente la tua infrastruttura telefonica esistente a ElevenLabs Agents. Questa integrazione consente a tutti i clienti di usare i sistemi telefonici esistenti sfruttando al contempo le funzionalità avanzate di IA vocale di ElevenLabs.

Con il SIP trunking puoi:

• Collegare il tuo Private Branch Exchange (PBX) o sistema telefonico abilitato per SIP alla piattaforma di IA vocale di ElevenLabs
• Instradare le chiamate agli agenti IA senza modificare la tua infrastruttura telefonica esistente
• Gestire chiamate sia in entrata sia in uscita
• Sfruttare il trasporto TLS crittografato e la crittografia dei contenuti multimediali per una maggiore sicurezza

Come funziona il SIP trunking

Il SIP trunking stabilisce una connessione diretta tra la tua infrastruttura telefonica e la piattaforma ElevenLabs:

1. Chiamate in entrata: le chiamate dal tuo SIP trunk vengono instradate alla piattaforma ElevenLabs usando l’indirizzo SIP INVITE configurato.
2. Chiamate in uscita: le chiamate avviate da ElevenLabs vengono instradate al tuo SIP trunk usando l’hostname configurato, consentendo ai tuoi agenti di effettuare chiamate in uscita.
3. Autenticazione: la sicurezza della connessione per la segnalazione viene mantenuta tramite autenticazione digest (nome utente/password) o autenticazione Access Control List (ACL) basata sull’IP di origine della segnalazione.
4. Segnalazione e contenuti multimediali: la configurazione iniziale della chiamata (segnalazione) supporta più protocolli di trasporto, incluso TLS per la comunicazione crittografata. Una volta stabilita la chiamata, i dati audio effettivi (stream RTP) possono essere crittografati in base alle impostazioni di crittografia dei contenuti multimediali.

Sicurezza del trasporto: certificati e suite di cifratura

Quando usi il trasporto TLS, entrambe le parti eseguono un handshake TLS prima dello scambio di qualsiasi segnalazione SIP. Durante l’handshake convalidano un certificato e negoziano una suite di cifratura. La parte che accetta la connessione agisce come server TLS e presenta il certificato; la parte che apre la connessione agisce come client TLS e lo convalida. ElevenLabs richiede TLS 1.2 o versioni successive.

I ruoli dipendono dalla direzione della chiamata:

• Chiamate in entrata verso ElevenLabs: il tuo sistema apre la connessione, quindi ElevenLabs agisce come server TLS. ElevenLabs presenta un certificato valido per sip.rtc.elevenlabs.io, che il tuo sistema convalida come client TLS.
• Chiamate in uscita da ElevenLabs: ElevenLabs apre la connessione all’indirizzo configurato, quindi il tuo server SIP o SBC agisce come server TLS. Il tuo sistema deve presentare un certificato valido e attendibile, che ElevenLabs convalida come client TLS.

Assicurati che entrambe le parti considerino attendibili i rispettivi certificati e condividano almeno una suite di cifratura comune. In caso contrario, l’handshake TLS non riesce prima che la chiamata venga stabilita. Consulta il riferimento SIP per le definizioni di questi termini.

Connessioni successive

Alcune richieste in-dialogo, come BYE o REFER, potrebbero richiedere una nuova connessione TLS quando quella originale è già stata chiusa. Il comportamento dei certificati per queste connessioni successive differisce dalla configurazione iniziale della chiamata:

• Connessioni successive a ElevenLabs: il tuo sistema stabilisce la connessione all’indirizzo dell’header Contact restituito nella risposta, che viene risolto in uno specifico server SIP nel formato <ip>.hosts.rtc.elevenlabs.io. Quel server presenta un certificato valido per *.hosts.rtc.elevenlabs.io, che il tuo sistema convalida come client TLS.
• Connessioni successive da ElevenLabs: quando ElevenLabs avvia una connessione TLS per un BYE o REFER, si connette all’indirizzo nell’header Via più in alto, che spesso è un indirizzo IP. Il tuo sistema restituisce in genere un certificato valido per un nome di dominio completo (FQDN) anziché per quell’indirizzo IP. Per convalidare questo certificato, configura il campo Domini remoti nelle impostazioni del numero di telefono. Se un dominio per cui il certificato ricevuto è valido corrisponde a un dominio remoto configurato, la convalida riesce; altrimenti non riesce.

Effettuare chiamate al SIP trunk di ElevenLabs

Quando avvii chiamate alla piattaforma ElevenLabs, devi usare il formato URI SIP corretto. L’URI del SIP trunk di ElevenLabs dipende dal trasporto che vuoi usare per la segnalazione:

• TCP: sip:sip.rtc.elevenlabs.io:5060;transport=tcp
• TLS: sip:sip.rtc.elevenlabs.io:5061;transport=tls
• UDP: sip:sip.rtc.elevenlabs.io:5060;transport=udp (sperimentale; usalo solo per i test, non in produzione)

Per effettuare una chiamata, costruisci un URI SIP completo che includa un identificatore. Ad esempio, per chiamare il numero di telefono +19991234567 tramite TCP:

sip:+19991234567@sip.rtc.elevenlabs.io:5060

Dove:

• +19991234567 è l’identificatore (in genere un numero di telefono in formato E.164)
• L’identificatore può anche essere qualsiasi valore stringa, ad esempio 1000 o john

Requisiti

Prima di configurare il SIP trunking, assicurati di avere:

1. Un PBX o sistema telefonico compatibile con SIP
2. Numeri di telefono che vuoi collegare a ElevenLabs
3. Accesso amministratore alla configurazione del tuo SIP trunk
4. Impostazioni del firewall appropriate per consentire il traffico SIP
5. Supporto TLS: per una maggiore sicurezza, assicurati che il tuo provider SIP supporti il trasporto TLS
6. Compatibilità dei codec audio: Il tuo sistema deve supportare almeno uno dei codec audio G.722 o G.711 (PCMU o PCMA), oppure essere in grado di ricampionare l’audio dal tuo lato. Questo è indipendente da qualsiasi formato audio configurato sull’agente per le connessioni websocket dirette.

Configurare il SIP trunking

1

Vai a Numeri di telefono

Vai alla sezione Numeri di telefono nella dashboard di ElevenLabs Agents.

2

Importa SIP Trunk

Fai clic sul pulsante “Importa numero”, quindi seleziona “Da SIP Trunk” per aprire la finestra di configurazione.

3

Inserisci la configurazione di base

Completa la configurazione di base con le seguenti informazioni:

• Etichetta: un nome descrittivo per il numero di telefono
• Numero di telefono: il numero di telefono in formato E.164 da collegare (ad es. +15551234567)

4

Configura le impostazioni in entrata

Configura il modo in cui ElevenLabs gestisce le chiamate che arrivano al tuo SIP trunk, inclusi la crittografia dei contenuti multimediali e i controlli di accesso:

• Crittografia dei contenuti multimediali: configura la crittografia per gli stream multimediali RTP:
  • Disabilitata: nessuna crittografia dei contenuti multimediali
  • Consentita: consente stream multimediali crittografati
  • Obbligatoria: impone stream multimediali crittografati
• Numeri consentiti (facoltativo): numeri di telefono autorizzati a chiamare questo numero. Lascia vuoto per consentire tutti i numeri.
• Indirizzi IP di origine consentiti (facoltativo): funziona solo per il trasporto TCP/TLS, non UDP. Indirizzi IP o intervalli CIDR autorizzati a inviare chiamate a questo trunk. Lascia 0.0.0.0/0 per consentire tutti gli indirizzi.
• Domini remoti (facoltativo): specifica i domini FQDN dei tuoi server SIP dai quali hanno origine le chiamate, ad esempio example.pstn.twilio.com. Questi domini vengono usati per la convalida dei certificati TLS. Lascia vuoto questo campo se non usi TLS.
• Autenticazione (facoltativo): fornisci le credenziali di autenticazione digest che verranno usate per autenticare le chiamate in entrata.
  • Nome utente SIP Trunk: nome utente per l’autenticazione SIP digest
  • Password SIP Trunk: password per l’autenticazione SIP digest

5

Configura le impostazioni in uscita

Configura dove ElevenLabs deve inviare le chiamate per il tuo numero di telefono:

• Indirizzo: hostname o indirizzo IP a cui viene inviato il SIP INVITE (ad es. sip.telnyx.com). Deve essere solo un hostname o un indirizzo IP, non un URI SIP completo. Se usi TLS, usa un hostname con un certificato valido.

• Tipo di trasporto: seleziona il protocollo di trasporto per la segnalazione SIP:

  • TCP: trasporto TCP standard
  • TLS: trasporto TLS crittografato per una maggiore sicurezza
  • UDP: trasporto senza connessione (sperimentale; usa TCP o TLS in produzione)

• Crittografia dei contenuti multimediali: configura la crittografia per gli stream multimediali RTP:

  • Disabilitata: nessuna crittografia dei contenuti multimediali
  • Consentita: consente stream multimediali crittografati
  • Obbligatoria: impone stream multimediali crittografati

• Codec abilitati: codec da offrire nell’SDP per le chiamate in uscita (G.722, PCMU, PCMA). Utile quando il tuo provider SIP supporta solo determinati codec.

• Header personalizzati (facoltativo): aggiungi header SIP personalizzati da includere nelle chiamate in uscita. Fai clic su “Aggiungi header” per inserire il nome e il valore dell’header richiesti dal tuo provider; puoi aggiungere più header secondo necessità. Gli header personalizzati possono essere usati per l’instradamento e l’identificazione delle chiamate, la fatturazione e il tracciamento, nonché per requisiti specifici del provider.

• Autenticazione (facoltativo): fornisci le credenziali di autenticazione digest se richieste dal tuo provider SIP trunk.

  • Nome utente SIP Trunk: nome utente per l’autenticazione SIP digest
  • Password SIP Trunk: password per l’autenticazione SIP digest

  Se lasciato vuoto, verrà usata l’autenticazione Access Control List (ACL), che richiede di inserire gli indirizzi IP di ElevenLabs nella allowlist nelle impostazioni del tuo provider.

Best practice di sicurezza: usa il trasporto TLS con crittografia dei contenuti multimediali obbligatoria per la massima sicurezza. In questo modo, sia la segnalazione sia i contenuti multimediali sono crittografati end-to-end.

Metodi di autenticazione:

• Autenticazione digest: usa credenziali di nome utente/password per un’autenticazione sicura (consigliata)
• Autenticazione ACL: usa l’inserimento di indirizzi IP nella allowlist per il controllo degli accessi

L’autenticazione digest è fortemente consigliata perché offre una maggiore sicurezza senza dipendere dall’inserimento degli IP nella allowlist, che può essere complesso da gestire con indirizzi IP dinamici.

Il campo Indirizzo specifica dove ElevenLabs invierà le chiamate in uscita dai tuoi agenti IA. Inserisci solo l’hostname o l’indirizzo IP senza il prefisso del protocollo sip:.

6

Completa la configurazione

Fai clic su “Importa” per finalizzare la configurazione.

Dati del cliente e personalizzazione

Per garantire il corretto inoltro e la tracciabilità dei metadati delle chiamate, includi i seguenti header SIP personalizzati nel payload del webhook e nella richiesta SIP INVITE:

• X-CALL-ID: identificatore univoco della chiamata
• X-CALLER-ID: identificatore del chiamante

Questi header consentono al sistema di associare i metadati della chiamata alla conversazione e di fornire contesto per la personalizzazione.

Supporto per header di fallback

Se gli header standard sopra indicati non sono presenti, il sistema cercherà automaticamente l’header SIP specifico di Twilio:

• sip.twilio.callSid: identificatore univoco della chiamata Twilio

Questo fallback garantisce la compatibilità con Elastic SIP Trunking di Twilio senza richiedere modifiche alla configurazione.

Flusso di elaborazione

Una volta ricevuti i metadati pertinenti tramite uno qualsiasi degli header supportati, caller_id e/o call_id sono disponibili nel webhook di avvio della conversazione e come variabili dinamiche di sistema.

Header personalizzati in entrata come variabili dinamiche

Gli header SIP personalizzati X- provenienti dalle chiamate SIP trunk in entrata vengono esposti automaticamente come variabili dinamiche nella conversazione.

I nomi degli header vengono normalizzati rimuovendo il prefisso X-, convertendo il nome in minuscolo, sostituendo i trattini con trattini bassi e aggiungendo il prefisso sip_. Ad esempio, X-Contact-ID diventa {{sip_contact_id}} e X-Campaign-ID diventa {{sip_campaign_id}}.

Usa queste variabili nei prompt dell’agente, nei primi messaggi e negli strumenti per personalizzare la conversazione con il contesto fornito dal chiamante. I valori sono visibili anche nella cronologia della conversazione nella scheda Chiamata telefonica.

Header BYE da variabili dinamiche

Quando una chiamata termina, ElevenLabs invia un SIP BYE per chiudere il dialogo. Puoi allegare header personalizzati a quel BYE mappando le variabili dinamiche ai nomi degli header nella configurazione del tuo SIP trunk.

Imposta attributes_to_headers su inbound_trunk_config o outbound_trunk_config quando crei o aggiorni un numero di telefono SIP trunk tramite l’API. Ogni voce mappa il nome di una variabile dinamica al nome dell’header SIP da includere nel BYE:

"inbound_trunk_config": {
  "attributes_to_headers": {
    "dynamic_variable_name": "bye_header_name"
  }
}

Il valore dell’header è il valore finale della variabile dinamica al termine della conversazione. I valori impostati durante la chiamata, tramite strumenti dell’agente, override del webhook o altri aggiornamenti di runtime, vengono riportati nel BYE.

Ad esempio, se attributes_to_headers contiene "disposition_code": "X-Disposition" e la variabile dinamica disposition_code è resolved al termine della conversazione, il BYE include X-Disposition: resolved.

Assegnare agenti ai numeri di telefono

Dopo aver importato il numero di telefono del tuo SIP trunk, puoi assegnarlo a un agente ElevenLabs:

1. Vai alla sezione Numeri di telefono nella dashboard di ElevenAgents
2. Seleziona il numero di telefono SIP trunk importato
3. Fai clic su “Assegna agente”
4. Seleziona l’agente che vuoi gestisca le chiamate a questo numero

Risoluzione dei problemi

Limitazioni e considerazioni

• Il supporto per più chiamate simultanee dipende dal tuo piano di abbonamento. Abilita l’accodamento delle chiamate per mettere in attesa i chiamanti in entrata quando viene raggiunto il limite, invece di rifiutarli
• Le funzionalità di registrazione delle chiamate e analisi sono disponibili, ma potrebbero richiedere una configurazione aggiuntiva
• Le funzionalità di chiamata in uscita potrebbero essere limitate dal tuo provider di trunk SIP
• Supporto TLS: assicurati che il tuo provider di trunk SIP supporti TLS 1.2 o versioni successive per il trasporto crittografato
• Crittografia multimediale: il supporto SRTP varia a seconda del provider; verifica la compatibilità prima di rendere obbligatoria la crittografia
• Formato audio: l’implementazione SIP di ElevenLabs invia e riceve audio tramite i codec PCMU o PCMA (G.711, 8 kHz) oppure G.722 (16 kHz). Questo è indipendente da qualsiasi formato audio configurato sull’agente per le connessioni websocket dirette. Il tuo sistema di trunk SIP deve supportare nativamente uno di questi codec oppure eseguire il ricampionamento per soddisfare i requisiti del tuo sistema

Domande frequenti

Passaggi successivi

• Riferimento SIP: glossario dei termini SIP e di rete
• Scopri come creare agenti ElevenLabs