Riferimento SIP
Panoramica
Il SIP trunking collega la tua infrastruttura di telefonia esistente a ElevenLabs Agents. La sua configurazione prevede protocolli, impostazioni di rete e formati audio che utilizzano una terminologia specializzata.
Questa pagina definisce questi termini in modo chiaro. Usala come riferimento mentre leggi la guida al SIP trunking o risolvi i problemi di connessione.
I termini sono raggruppati nelle seguenti categorie:
- Protocolli — gli standard che trasportano segnalazione e audio.
- Trasporto e rete — il modo in cui i pacchetti viaggiano tra i sistemi.
- Componenti dell’infrastruttura — i sistemi che gestiscono le chiamate.
- Segnalazione delle chiamate — i messaggi che avviano e terminano una chiamata.
- Autenticazione e sicurezza — come le connessioni vengono verificate e crittografate.
- Audio e codec — come il parlato viene codificato e trasmesso.
- Indirizzamento e instradamento — come le chiamate raggiungono la loro destinazione.
- Configurazione di ElevenLabs — impostazioni specifiche della dashboard di ElevenLabs.
Protocolli
SIP (Session Initiation Protocol)
Il protocollo di segnalazione che avvia, modifica e termina sessioni di comunicazione in tempo reale come le chiamate vocali. SIP negozia chi chiama chi e come deve essere scambiato l’audio, ma non trasporta l’audio stesso. È definito in RFC 3261.
SDP (Session Description Protocol)
Un formato di testo incluso nei messaggi SIP che descrive i media di una chiamata: quali codec supporta ciascuna parte, gli indirizzi IP e le porte per il flusso audio e i parametri di crittografia. I due endpoint usano SDP per concordare una configurazione comune prima che inizi il flusso audio.
RTP (Real-time Transport Protocol)
Il protocollo che trasporta l’audio effettivo di una chiamata dopo che SIP l’ha avviata. I pacchetti RTP viaggiano in un flusso continuo e sono sensibili a ritardi e perdite, per questo la qualità audio dipende dalle condizioni della rete.
SRTP (Secure RTP)
Una versione crittografata di RTP. Quando la crittografia dei media è abilitata, il flusso audio viene protetto con SRTP per evitare che venga intercettato durante il transito. Per utilizzare i media crittografati, entrambi gli endpoint devono supportare SRTP.
RTCP (RTP Control Protocol)
Un protocollo complementare a RTP che segnala statistiche come la perdita di pacchetti e il jitter, consentendo agli endpoint di monitorare la qualità della chiamata.
Trasporto e rete
UDP (User Datagram Protocol)
Un trasporto veloce e senza connessione che invia pacchetti senza garantire la consegna o l’ordine. L’audio RTP viene trasportato su UDP perché, per il parlato in tempo reale, una bassa latenza è più importante di una consegna perfetta.
Il trasporto UDP per la segnalazione SIP è sperimentale su ElevenLabs. Per il traffico di produzione usa TCP o TLS e scegli UDP solo per i test.
TCP (Transmission Control Protocol)
Un trasporto orientato alla connessione che garantisce una consegna affidabile e ordinata. ElevenLabs supporta TCP per la segnalazione SIP sulla porta 5060.
TLS (Transport Layer Security)
Un livello di crittografia che opera sopra TCP. Il trasporto TLS crittografa la segnalazione SIP, in modo che credenziali e metadati delle chiamate non possano essere letti durante il transito. ElevenLabs supporta TLS per la segnalazione sulla porta 5061.
MTU (Maximum Transmission Unit)
La dimensione massima di un pacchetto, in byte, che un collegamento di rete può trasportare senza dividerlo in parti più piccole. Quando un messaggio SIP su UDP supera l’MTU, può essere frammentato o scartato, causando potenzialmente errori nell’avvio della chiamata. La segnalazione SIP inviata su TCP o TLS evita questo problema perché questi trasporti gestiscono in modo affidabile i messaggi di grandi dimensioni.
NAT (Network Address Translation)
Una tecnica utilizzata dai router per condividere un indirizzo IP pubblico tra molti dispositivi in una rete privata. Il NAT può impedire all’audio RTP di raggiungere il dispositivo corretto, una causa comune di audio unidirezionale o assente.
Latenza
Il ritardo tra l’invio dell’audio e la sua ricezione. Un’elevata latenza rende le conversazioni innaturali perché ogni parte deve attendere più a lungo per sentire l’altra.
Jitter
La variazione nel tempo di arrivo dei pacchetti audio. Un jitter elevato provoca audio discontinuo o distorto, anche quando la latenza complessiva è accettabile.
Perdita di pacchetti
La percentuale di pacchetti audio che non arriva mai. Anche piccole quantità di perdita di pacchetti peggiorano la qualità audio perché RTP non ritrasmette i pacchetti persi.
Porta
Un endpoint numerato su un indirizzo IP che identifica un servizio specifico. La segnalazione SIP usa la porta 5060 per TCP e la 5061 per TLS; i media RTP usano in genere un’ampia gamma di porte assegnate dinamicamente.
Componenti dell’infrastruttura
SBC (Session Border Controller)
Un dispositivo o servizio posto al confine di una rete per gestire e proteggere il traffico SIP. Un SBC svolge attività quali la protezione da accessi non autorizzati, la normalizzazione dei messaggi SIP tra sistemi che implementano il protocollo in modo diverso e la gestione dell’attraversamento NAT. Molti provider di SIP trunk collocano un SBC tra la loro rete e la tua.
PBX (Private Branch Exchange)
Un sistema telefonico privato che instrada le chiamate all’interno di un’organizzazione e le collega a linee esterne. Un PBX abilitato per SIP può connettersi a ElevenLabs tramite un SIP trunk.
SIP trunk
Una connessione virtuale tra il tuo sistema di telefonia e un servizio vocale che trasporta più chiamate simultanee via internet anziché tramite linee telefoniche fisiche. Un SIP trunk collega il tuo PBX o provider a ElevenLabs.
Segnalazione delle chiamate
SIP INVITE
Il messaggio SIP che richiede una nuova chiamata. INVITE include l’identificatore di destinazione e una descrizione SDP delle capacità media del chiamante.
200 OK
La risposta SIP che conferma il successo di una richiesta. Per un INVITE, il messaggio 200 OK include l’SDP della parte che risponde e un indirizzo Contact che identifica il server esatto che gestisce la chiamata.
BYE
Il messaggio SIP che termina una chiamata stabilita. Un BYE deve essere inviato all’indirizzo Contact restituito nel 200 OK, affinché raggiunga lo stesso server che ha gestito la chiamata.
Header Contact
Un campo in una risposta SIP che identifica il server e l’indirizzo precisi per i messaggi successivi nella stessa chiamata. ElevenLabs fornisce traffico SIP da più server dietro l’indirizzo condiviso sip.rtc.elevenlabs.io, quindi l’invio di richieste successive, come un BYE, a quell’indirizzo condiviso anziché all’indirizzo Contact può farle arrivare a un server diverso.
Dialogo
Lo stato condiviso che due endpoint mantengono per la durata di una chiamata. Se un messaggio come un BYE raggiunge un server che non ha alcuna registrazione del dialogo, il server lo rifiuta.
Codici di risposta
Numeri a tre cifre che indicano il risultato di una richiesta SIP, simili ai codici di stato HTTP. I codici nell’intervallo 1xx sono provvisori e segnalano l’avanzamento: 100 (Trying) conferma che la richiesta è stata ricevuta ed è in elaborazione, mentre 180 (Ringing) indica che la destinazione sta ricevendo la notifica della chiamata. Le risposte finali indicano l’esito: 200 (OK) significa successo, 401 e 407 indicano che è richiesta l’autenticazione e 481 significa che il server non ha un dialogo corrispondente per la richiesta.
Autenticazione e sicurezza
Autenticazione digest
Un metodo di autenticazione che verifica una connessione usando nome utente e password senza inviare la password in testo normale. ElevenLabs consiglia l’autenticazione digest perché non dipende da indirizzi IP fissi.
ACL (Access Control List)
Un metodo di autenticazione basato sull’allowlist di indirizzi IP attendibili. Con l’autenticazione ACL, un sistema accetta traffico SIP solo dagli indirizzi di origine approvati. Può essere più difficile da gestire quando gli indirizzi IP cambiano.
Crittografia dei media
La protezione applicata al flusso audio RTP tramite SRTP. ElevenLabs offre tre impostazioni: Disabled (nessuna crittografia), Allowed (crittografa quando entrambe le parti lo supportano) e Required (rifiuta le chiamate che non possono essere crittografate).
Certificato
Un documento digitale X.509 che dimostra l’identità di un server durante un handshake TLS. 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 rispetto a un’autorità di certificazione attendibile, verificando hostname e scadenza. I ruoli differiscono in base alla direzione della chiamata:
- Chiamate in entrata verso ElevenLabs: il tuo sistema apre la connessione, quindi ElevenLabs agisce come server TLS e presenta un certificato per
sip.rtc.elevenlabs.io, che il tuo sistema convalida. - Chiamate in uscita da ElevenLabs: ElevenLabs apre la connessione, quindi il tuo server SIP o SBC agisce come server TLS e deve presentare un certificato valido e attendibile, che ElevenLabs convalida.
Suite di cifratura
L’insieme di algoritmi che una connessione TLS utilizza per scambiare chiavi, crittografare dati e verificarne l’integrità. Durante l’handshake, il client TLS offre le suite di cifratura supportate e il server TLS ne seleziona una in comune. ElevenLabs richiede TLS 1.2 o versioni successive. Per le chiamate in entrata verso ElevenLabs, ElevenLabs (come server TLS) seleziona la suite; per le chiamate in uscita da ElevenLabs, il tuo sistema (come server TLS) la seleziona. Entrambe le parti devono condividere almeno una suite di cifratura moderna, altrimenti l’handshake fallisce prima della connessione della chiamata.
Audio e codec
Codec
Un algoritmo che comprime l’audio per la trasmissione e lo decomprime all’altra estremità. Perché una chiamata abbia audio, entrambi gli endpoint devono supportare un codec comune.
G711
Un codec non compresso ampiamente supportato, che trasporta audio a una frequenza di campionamento di 8 kHz. È la scelta più compatibile tra i sistemi di telefonia.
G722
Un codec a banda larga che trasporta audio a una frequenza di campionamento di 16 kHz, offrendo un parlato più nitido rispetto a G711 quando entrambi gli endpoint lo supportano.
Frequenza di campionamento
Il numero di volte al secondo in cui l’audio viene misurato, espresso in kilohertz (kHz). La distribuzione SIP di ElevenLabs invia e riceve audio come G711 a 8 kHz o G722 a 16 kHz. I sistemi che usano altre frequenze devono ricampionare l’audio.
DTMF (Dual-Tone Multi-Frequency)
I toni prodotti premendo i tasti del tastierino telefonico, usati per navigare nei menu automatici. Consulta input DTMF per sapere come gli agenti ricevono le cifre del tastierino e riprodurre il tono dei tasti per sapere come gli agenti inviano DTMF.
Indirizzamento e instradamento
URI SIP
L’indirizzo usato per raggiungere una destinazione SIP, scritto come sip:identifier@domain:port. Ad esempio, sip:+19991234567@sip.rtc.elevenlabs.io:5060 instrada una chiamata all’identificatore +19991234567. L’identificatore è obbligatorio affinché la chiamata possa essere instradata.
E.164
Lo standard internazionale per la formattazione dei numeri di telefono, composto da un + iniziale, un prefisso nazionale e il numero dell’abbonato, ad esempio +15551234567. Il formato deve corrispondere tra il tuo URI SIP e il numero di telefono importato.
Record NAPTR e SRV
Tipi di record DNS che consentono a un sistema SIP di individuare quali server, trasporti e porte usare per un dominio. ElevenLabs pubblica record NAPTR e SRV per l’individuazione di server conforme a RFC 3263.
Configurazione di ElevenLabs
Tipo di trasporto
Il protocollo selezionato per la segnalazione SIP nella dashboard. ElevenLabs supporta TCP (porta 5060) e TLS (porta 5061). TLS è consigliato per la produzione perché crittografa la segnalazione.
Configurazione in entrata
Le impostazioni che controllano come le chiamate in arrivo dal tuo SIP trunk raggiungono ElevenLabs, inclusi il tipo di trasporto e la crittografia dei media applicata alle chiamate in entrata.
Configurazione in uscita
Le impostazioni che controllano come ElevenLabs invia le chiamate al tuo sistema, incluso l’Address (un hostname o indirizzo IP, senza il prefisso sip:) a cui viene recapitato il SIP INVITE.
Header personalizzati
Campi header SIP aggiuntivi con prefisso X- che puoi allegare alle chiamate per instradamento, identificazione o requisiti specifici del provider. Gli header personalizzati in entrata sono disponibili anche come variabili dinamiche nella conversazione. Gli header INVITE in uscita sono configurati con il campo statico headers in outbound_trunk_config.
User-to-User Information (UUI)
Un piccolo payload applicativo scambiato nell’header SIP User-to-User (RFC 7433), comunemente usato da piattaforme per contact center come Talkdesk e Genesys Cloud. Nelle chiamate in entrata, quando l’INVITE include un header User-to-User, il relativo valore viene esposto all’agente come due variabili dinamiche: {{sip_uui_raw}} (il valore raw dell’header) e {{sip_uui_data}} (il payload decodificato — decodificato da esadecimale, con l’ottetto protocol-discriminator rimosso quando l’header include purpose=isdn-uui). Nelle chiamate in uscita, UUI viene allegato ai trasferimenti SIP REFER che hanno come destinazione un URI SIP tramite l’impostazione uui della regola di trasferimento — consulta Trasferimento a un numero.
Attributi negli header
Un’impostazione disponibile solo tramite API in inbound_trunk_config e outbound_trunk_config che associa i nomi delle variabili dinamiche ai nomi degli header SIP per le richieste BYE. Ogni chiave è un nome di variabile dinamica; ogni valore è il nome dell’header da includere al termine della chiamata. Il valore dell’header è il valore finale della variabile alla fine della conversazione. Consulta header BYE dalle variabili dinamiche.
Domini remoti
Un’impostazione del numero di telefono che elenca i domini accettati da ElevenLabs durante la convalida del certificato TLS sulle connessioni successive avviate da ElevenLabs (ad esempio un BYE o REFER). Poiché ElevenLabs si connette spesso a un indirizzo IP ricavato dall’header Via più in alto anziché a un hostname, non può associare il certificato soltanto in base all’hostname. Se un dominio per cui il certificato ricevuto è valido corrisponde a un dominio remoto configurato, la convalida riesce; altrimenti fallisce. Consulta connessioni successive.
Server SIP con IP statico
Un’opzione Enterprise che fornisce endpoint SIP con intervalli IP fissi per i clienti le cui policy di sicurezza richiedono l’allowlist degli IP. Per i dettagli, consulta la guida al SIP trunking.