Trunk SIP

Un trunk SIP collega il tuo sistema telefonico a Bird. Fornisce al tuo PBX, il centralino che instrada le chiamate, un indirizzo per le chiamate in uscita, definisce come Bird le autentica e può anche ricevere le chiamate in arrivo sui numeri che possiedi. Configura i trunk in Voice > SIP Trunks.

La maggior parte delle configurazioni richiede un solo trunk. Crea trunk separati quando sedi o sistemi necessitano di liste di IP consentiti, chiavi API, impostazioni delle credenziali di sessione o algoritmi Digest diversi.

Creare un trunk

Seleziona Create trunk e inserisci un nome. Puoi modificare questa etichetta della dashboard in seguito; non viene inviata con le chiamate.

Bird assegna un dominio SIP fisso al trunk. Inserisci questo dominio nel tuo sistema telefonico in modo che Bird possa associare le chiamate al trunk.

Un nuovo trunk rifiuta ogni chiamata finché non indichi chi può effettuarle: un intervallo IP, una chiave API, credenziali di sessione o una combinazione.

Direzione delle chiamate

Un trunk gestisce ciascuna direzione separatamente, e un nuovo trunk non ne gestisce nessuna. La pagina del trunk ha una sezione per direzione, e una direzione disattivata mostra solo il controllo per attivarla.

Outbound calling indica che il tuo PBX effettua chiamate tramite Bird. Seleziona Enable outbound. Finché non è attivato, il trunk rifiuta ogni tentativo in uscita indipendentemente dalle credenziali. I dettagli di connessione del trunk, le liste di IP consentiti, le chiavi, le credenziali di sessione e l'offerta Digest si trovano tutti in questa sezione, perché regolano chi può connettersi.

Inbound calling indica che Bird consegna le chiamate al tuo PBX, per i numeri a cui risponde questo trunk. Seleziona Enable inbound, poi aggiungi almeno un gateway di consegna: un trunk senza gateway rifiuta ogni chiamata in arrivo ai suoi numeri. La lista Inbound numbers della sezione mostra quali dei tuoi numeri inviano le chiamate qui.

L'associazione di un numero al trunk si fa dal numero, non da qui. Consulta Ricezione delle chiamate per questo e per il significato dei formati numerici di un gateway.

Warning: turning inbound calling off puts every number pointing at this trunk back on reject, and turning it back on does not restore them. Deleting the trunk does the same.

Dettagli di connessione

Apri un trunk per vedere cosa inserire nel tuo PBX:

Impostazione	Valore
Dominio SIP	Il dominio proprio del trunk. Copialo per intero dalla pagina del trunk
Username	Sempre bird
Password	Il secret di una chiave API consentita su questo trunk (vedi Autenticazione con chiave API)

Note: with the IP allow list alone, the SIP domain and a port are all you need: the username and password are for API key authentication. A client holding a session credential uses the password from that credential instead.

Invia le chiamate al dominio SIP su una di queste porte:

Trasporto	Porta	Note
UDP	5060	La porta predefinita che la maggior parte degli apparati assume
TCP	5060	Stessa porta di UDP, quindi scegli il trasporto sul tuo PBX
TLS	5061	SIP su TLS, per la segnalazione che vuoi cifrata in transito

Controllare chi può inviare chiamate

Un trunk può autenticare gli apparati in base all'indirizzo IP di origine, alla chiave API o a una credenziale di sessione a breve scadenza. Attiva i metodi necessari ai tuoi client.

Configurali in IP allow list, Allowed API keys e Session credentials. Le modifiche salvate si applicano alle nuove chiamate.

Lista di IP consentiti

Aggiungi gli indirizzi pubblici da cui i tuoi apparati inviano SIP, come indirizzi singoli o intervalli CIDR, ciascuno con una descrizione opzionale. Il filtraggio IP si attiva appena la lista contiene una voce: da quel momento, solo gli intervalli elencati possono inviare chiamate a questo trunk.

Aggiungi l'indirizzo pubblico di origine che raggiunge Bird. Per apparati dietro NAT, usa l'indirizzo pubblico del router invece dell'indirizzo privato del sistema telefonico. Bird rifiuta le chiamate da indirizzi non in lista al livello SIP, quindi di solito non compaiono nel registro chiamate. Consulta la risoluzione dei problemi voce per le chiamate mancanti.

Autenticazione con chiave API

Bird può invece (o anche) richiedere una password per ogni chiamata. Lo scambio è l'autenticazione Digest SIP: Bird invia una challenge, il tuo sistema telefonico risponde con un hash della password anziché la password stessa, e Bird la verifica rispetto a una chiave Bird API.

Assegna a una chiave API il permesso voice a livello write, che è il livello su cui un trunk autentica. Aggiungilo a una chiave che hai già, oppure creane una nuova. In entrambi i casi il secret della chiave resta invariato: una chiave già distribuita mantiene il secret con cui i tuoi sistemi sono configurati, e una chiave nuova mostra il secret una sola volta, alla creazione, quindi salvalo in quel momento. Vedi Chiavi API.
Nella pagina del trunk, sotto Allowed API keys, aggiungi quella chiave.
Nel tuo PBX, imposta lo username su bird e la password sul secret della chiave.

L'autenticazione con chiave API si attiva appena la lista contiene una chiave: da quel momento, solo le chiavi elencate possono autenticarsi.

Rimuovere il permesso voice da una chiave ne blocca l'autenticazione immediatamente, ma il trunk la mantiene nella lista delle chiavi consentite. Riaggiungi il permesso e il trunk funziona di nuovo con lo stesso secret, senza modifiche al trunk o al tuo PBX. Mentre il permesso manca, la pagina del trunk contrassegna quella chiave in modo che la lista delle chiavi consentite non appaia funzionante quando non lo è.

Revocare o eliminare una chiave API ne rimuove immediatamente la capacità di autenticazione, su ogni trunk che la consentiva, e questa azione è permanente. Per ruotare, aggiungi prima la nuova chiave al trunk, sposta i tuoi apparati, poi revoca quella vecchia.

Credenziali di sessione

Una credenziale di sessione è uno username e una password SIP a breve scadenza. Risponde alla stessa challenge Digest di una chiave API senza esporre un secret di lunga durata.

Attivale sotto Session credentials nella pagina del trunk; su un nuovo trunk sono disattivate. Cosa ammettono:

Il telefono nella dashboard, che ne genera una per chiamata automaticamente.
Un client SIP gestito dalla CLI: bird voice tools test-call ne genera una per la chiamata che effettua, e bird voice session-credentials create ne genera una da incollare in qualsiasi altro client. Entrambi richiedono accesso voice a livello write.

Una credenziale appartiene allo spazio di lavoro e non a un singolo trunk, quindi un client può usarla su tutti i trunk idonei. Il client deve presentare la credenziale e il trunk deve avere le credenziali di sessione attivate. Bird restituisce la password solo al momento della generazione.

Attivarle non cambia il modo in cui si connettono gli apparati nella lista di IP consentiti: una chiamata da un indirizzo in lista, su un trunk senza chiavi API consentite, viene comunque ammessa senza richiesta di password.

Algoritmo Digest

Per impostazione predefinita Bird offre prima SHA-256 e poi MD5. Il tuo PBX risponde con il primo algoritmo che supporta.

Modifica l'offerta in Digest algorithm quando il tuo apparato lo richiede. Per un PBX che gestisce male una challenge che inizia con SHA-256, seleziona MD5 only. Un trunk accetta solo gli algoritmi che offre. Le chiavi API funzionano con entrambi gli algoritmi e non devono essere riemesse.

Mantieni MD5 nell'offerta su qualsiasi trunk da cui chiami con il telefono: un browser risponde con MD5 e nient'altro, quindi un trunk che offre solo SHA-256 rifiuta ogni chiamata dal browser.

Eliminare un trunk

L'eliminazione di un trunk ha effetto immediato: il suo dominio SIP smette di accettare nuove chiamate e ogni numero che punta a esso torna a rifiutare le chiamate. Le chiamate già in corso proseguono e i registri delle chiamate effettuate tramite il trunk restano nel tuo Registro chiamate.

Passi successivi

Pagina	Argomenti trattati
Effettua la tua prima chiamata	Da uno spazio di lavoro vuoto a un telefono che squilla
Telefono	Chiamare dalla dashboard, tramite un trunk che accetta credenziali di sessione
Effettuare chiamate	Cosa si aspetta Bird sulla INVITE e quanto costa una chiamata
Ricevere chiamate	Associare un numero a questo trunk e i suoi gateway di consegna
Caller ID	Registrare un numero e dimostrarne la proprietà con una chiamata di verifica
Chiavi API	Creare una chiave, scegliere i suoi scope e ruotarla

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Comprendi il concettoWhat is a voice API?Esplora la funzionalitàVoice Guida all'implementazioneVoice overview

Ottieni un brief di implementazione