FAQ Voice API
Cos'è Bird Voice?
Bird Voice consente di effettuare chiamate verso numeri di telefono tramite un trunk SIP. Il vostro sistema telefonico si collega a Bird e Bird instrada ogni chiamata attraverso un operatore verso la rete telefonica pubblica (la PSTN). Voi fornite il vostro PBX o softphone; Bird gestisce il tratto verso l'operatore.
Quanto velocemente posso effettuare la mia prima chiamata?
Circa dieci minuti. Create un trunk SIP, verificate un ID chiamante, abilitate il paese di destinazione e puntate il vostro sistema telefonico all'indirizzo del trunk. La guida alla prima chiamata vi accompagna in tutti i passaggi.
Di cosa ho bisogno prima di poter chiamare?
Tre cose dalla vostra parte: un trunk SIP con la vostra apparecchiatura autorizzata (per intervallo IP o API key), un ID chiamante verificato (il numero che presentate come chiamante) e il paese di destinazione abilitato. Bird associa l'instradamento al vostro workspace, che è il quarto prerequisito e avviene lato Bird.
Ho bisogno di hardware specifico?
No. Qualsiasi sistema telefonico compatibile SIP funziona: un softphone come Zoiper o Linphone su un laptop, un PBX come Asterisk o FreeSWITCH, o un sistema commerciale come 3CX o FreePBX. Bird vi fornisce un dominio SIP e voi puntate la vostra apparecchiatura verso di esso.
Posso effettuare chiamate dal browser?
Sì. Puoi effettuare chiamate dall'app Telefono della dashboard utilizzando WebRTC.
Come vengono tariffate le chiamate vocali?
Per chiamata, a una tariffa che dipende dal paese di destinazione. Ogni tariffa prevede un incremento di fatturazione: un tempo minimo fatturato, poi lo scatto a cui viene arrotondato successivamente. Una tariffa con un minimo di un minuto e scatti da sei secondi addebita una chiamata di 10 secondi per un minuto intero.
Quando inizia la fatturazione?
Il tempo fatturabile decorre dal momento in cui il numero chiamato risponde al momento in cui la chiamata termina. Il tempo di squillo non viene fatturato, quindi una chiamata a cui nessuno risponde non costa nulla.
La voce è prepagata o postpagata?
Prepagata, dal wallet della vostra organizzazione. Bird verifica il vostro saldo prima di contattare l'operatore, quindi una chiamata che il vostro wallet non può coprire viene rifiutata in anticipo con insufficient_balance anziché fatturata successivamente.
Esiste un limite di spesa giornaliero?
Sì. Per ogni organizzazione si applica un tetto di spesa giornaliero per le chiamate vocali, che si azzera all'inizio di ogni giorno UTC. Superato il limite, le chiamate vengono rifiutate con daily_spend_exceeded. L'importo dipende dal piano scelto e Bird può aumentarlo su richiesta.
Dove posso vedere il costo di una chiamata?
Apri la chiamata nel registro chiamate. Il costo compare nel record una volta che è stato tariffato, con massima precisione, al netto delle imposte. Per i totali su più chiamate, esporta l'elenco filtrato come CSV dalla pagina Chiamate oppure consulta le fatture e i dati di utilizzo.
Quali limiti si applicano alle mie chiamate?
Tre soglie: quante chiamate potete avere in corso contemporaneamente (chiamate simultanee), quante nuove chiamate potete avviare al secondo (chiamate al secondo) e quanto potete spendere in voce in un giorno UTC (spesa giornaliera). Ciascuna è impostata per organizzazione e gli importi dipendono dal vostro piano.
Cosa succede quando raggiungo un limite?
La chiamata viene rifiutata in fase di impostazione, prima che un operatore venga mai contattato. Il record della chiamata indica quale limite è stato raggiunto: concurrent_calls_exceeded, calls_per_second_exceeded o daily_spend_exceeded. Il vostro sistema telefonico riceve un SIP 503.
Posso aumentare i miei limiti?
Sì. Contattate il supporto per richiedere una soglia più alta per le chiamate simultanee o le chiamate al secondo. La soglia di spesa giornaliera dipende dal vostro piano e può anch'essa essere aumentata.
Un dialer per campagne viene rifiutato ma ho ampio margine di chiamate simultanee. Perché?
Controllate quale motivo riporta il record della chiamata. Un dialer può raggiungere calls_per_second_exceeded pur essendo ben lontano dalla soglia di chiamate simultanee, perché i due limiti sono indipendenti. Rallentate la frequenza di composizione e riprovate; riprovare immediatamente ottiene la stessa risposta.
Cos'è un SIP trunk?
Un SIP trunk è la connessione tra il tuo sistema telefonico e Bird. SIP (Session Initiation Protocol) è il linguaggio usato dai sistemi telefonici per impostare le chiamate, e un trunk è la linea su cui viaggiano. Bird assegna al tuo workspace un indirizzo trunk e tu punti il tuo sistema telefonico verso di esso.
Quanti trunk mi servono?
La maggior parte dei workspace ne richiede solo uno. Creane altri quando vuoi regole di accesso separate per sede o per sistema, poiché la lista IP consentiti, le API key autorizzate e le impostazioni Digest sono tutte per trunk.
Quali dettagli di connessione servono al mio PBX?
Il dominio SIP del trunk (copiato dalla pagina del trunk), il nome utente bird e la password (il segreto di una chiave API autorizzata sul trunk). Invia le chiamate al dominio SIP sulla porta 5060 (UDP o TCP) o 5061 (TLS).
Posso limitare chi invia chiamate al mio trunk?
Sì, con una lista IP consentiti, API key autorizzate o entrambe. Aggiungi gli indirizzi pubblici da cui i tuoi dispositivi inviano SIP oppure richiedi che ogni chiamata si autentichi con un'API key tramite SIP Digest. Entrambe le impostazioni hanno effetto dalla chiamata successiva.
Cosa succede quando elimino un trunk?
Il dominio SIP del trunk smette immediatamente di accettare nuove chiamate. Le chiamate già in corso proseguono e i record delle chiamate effettuate tramite il trunk restano nel registro chiamate.
Come funziona l'autenticazione SIP Digest?
Il tuo PBX invia la chiamata, Bird risponde con una challenge 407 e il tuo PBX reinvia la chiamata con un header Proxy-Authorization calcolato usando come username bird e come password il secret della tua API key. Il tuo PBX invia un hash della password, mai la password stessa.
Quali algoritmi Digest sono supportati?
SHA-256 e MD5. Bird propone SHA-256 per primo e MD5 per secondo di default, e il tuo PBX sceglie il primo che supporta. Se il tuo apparato gestisce solo MD5 e non elabora correttamente una challenge che inizia con SHA-256, imposta il trunk solo su MD5.
Posso usare sia la lista IP consentiti sia l'autenticazione tramite API key?
Sì. Quando un trunk ha entrambe, l'indirizzo sorgente viene verificato prima che Bird richieda una password, quindi una chiamata da un indirizzo non in lista viene rifiutata indipendentemente dalle credenziali fornite.
Come faccio a ruotare un'API key senza interruzioni di servizio?
Aggiungi prima la nuova chiave al trunk, sposta i tuoi apparati sulla nuova chiave, poi revoca quella vecchia. Revocare o eliminare una chiave rimuove immediatamente la sua capacità di autenticazione su tutti i trunk che la consentivano.
Cos'è un caller ID?
Un caller ID è un numero di telefono che il tuo workspace è autorizzato a presentare come chiamante nelle chiamate in uscita. Bird verifica il numero chiamante che il tuo apparato inserisce nell'header SIP From rispetto a questa lista ad ogni chiamata, quindi le chiamate escono solo con numeri che hai verificato.
Come verifico un caller ID?
Aggiungi il numero nella pagina Numeri in formato E.164. Bird effettua immediatamente una chiamata di verifica. Rispondi alla chiamata, ascolta un codice a sei cifre e inseriscilo nella dashboard. Hai cinque tentativi e il numero diventa utilizzabile non appena uno viene accettato.
La chiamata di verifica non è mai arrivata. Cosa faccio?
Se i tentativi sono esauriti, usa Ottieni un nuovo codice nella riga del numero per una nuova chiamata di verifica. Se il numero è ancora in attesa del codice, rimuovi l'ID chiamante e aggiungi nuovamente il numero.
Come verifico un numero che squilla su un sistema non presidiato?
Devialo su un telefono dove puoi rispondere per il minuto necessario alla verifica, poi ripristina la configurazione originale. Per un numero che non riceve chiamate, contatta il supporto.
Cosa succede quando rimuovo un caller ID?
Da quel momento, qualsiasi chiamata che presenta quel numero viene rifiutata con caller_id_not_verified. Le chiamate già in corso continuano e i registri delle chiamate che hanno usato quel numero restano invariati.
Perché devo abilitare i paesi prima di chiamare?
Le frodi telefoniche funzionano chiamando paesi costosi che non avresti mai voluto contattare. I paesi che abiliti sono quelli su cui puoi accumulare costi, quindi lasciare tutto il resto disattivato limita la tua esposizione in caso qualcuno violi il tuo sistema telefonico.
Come abilito un paese di destinazione?
Trova il paese nella pagina Destinations usando la casella di ricerca (corrispondenza per nome o codice a due lettere) e attiva il relativo interruttore. La modifica ha effetto da quel momento.
Cosa significa il badge High risk?
Le chiamate verso paesi ad alto rischio sono costose e chi gestisce il numero che chiami guadagna una parte del costo. Sono i paesi che un attaccante prende di mira se viola un sistema telefonico. Lasciali disattivati a meno che tu non abbia attività lì, e controlla la tariffa prima di abilitarne uno.
Un paese di cui ho bisogno è indicato come Not supported. Cosa faccio?
Contatta il supporto per farlo aprire sul tuo account. Available significa che puoi abilitarlo; Not supported significa che Bird al momento non può effettuare chiamate verso quel paese dal tuo account.
La mia chiamata è fallita con no_route_found ma il paese è abilitato. Perché?
Un paese disponibile può comunque avere destinazioni specifiche al suo interno che il routing non raggiunge ancora. Invia l'ID della chiamata al supporto e provvederanno a estendere il routing per coprirla.
Cosa si aspetta Bird nel SIP INVITE?
Due header: To (il numero chiamato) e From (il numero che presentate come chiamante, che deve essere un ID chiamante verificato). Entrambi devono essere numeri internazionali completi in formato E.164, un + iniziale seguito dal prefisso internazionale e dal numero nazionale. Non sono necessari header personalizzati.
Cos'è l'attestazione STIR/SHAKEN?
STIR/SHAKEN è una firma che gli operatori utilizzano per decidere se far passare una chiamata senza etichettatura. Le chiamate verso gli Stati Uniti e la Francia la includono automaticamente senza alcuna configurazione da parte vostra. Le chiamate hanno il livello B per impostazione predefinita; il livello A (il più forte) è disponibile su richiesta.
La mia chiamata è stata rifiutata. Come scopro il motivo?
Aprite la chiamata nel registro chiamate. Il vostro sistema telefonico riceve un semplice SIP 503, ma il motivo specifico è riportato nel record della chiamata dove solo voi potete leggerlo. Un pannello sopra i dettagli indica la causa e rimanda all'impostazione per risolverla.
Devo riprovare una chiamata rifiutata?
Solo quando la causa è stata risolta. Una chiamata rifiutata per calls_per_second_exceeded riceve la stessa risposta finché non rallentate la frequenza di composizione. Leggete il motivo del rifiuto prima di riprovare.
Quali stati delle chiamate esistono?
Cinque: Answered (il numero chiamato ha risposto), No answer (ha squillato senza risposta), Failed (la chiamata non è stata completata, Bird l'ha rifiutata o un carrier l'ha fatta fallire), Rejected (il carrier ha rifiutato direttamente la chiamata) e Unknown (l'esito non è stato determinabile).
Come distinguo un rifiuto di Bird da un errore del carrier?
Entrambi appaiono come Failed. È il motivo del rifiuto a distinguerli: solo un rifiuto di Bird ne include uno. Una chiamata fallita con un motivo di rifiuto indica un'impostazione dal tuo lato o da quello di Bird; una senza motivo di rifiuto di solito indica un problema con il numero composto.
Posso vedere le chiamate ancora in corso?
Sì. La scheda Live nella pagina Calls elenca le chiamate attive sui tuoi trunk in tempo reale, con un conteggio. Una chiamata attiva appare come Ringing (in attesa che l'altro lato risponda) o In progress (connessa). La scheda si aggiorna ogni pochi secondi.
Qual è la differenza tra durata totale e tempo fatturabile?
La durata totale parte dal momento in cui Bird ha ricevuto la chiamata fino alla chiusura. Il tempo fatturabile parte dalla risposta fino alla chiusura. La differenza è il tempo di squillo senza risposta, quindi un divario ampio merita un'analisi di ciò che stai chiamando. Una chiamata senza risposta non costa nulla.
Come faccio a esportare i registri delle chiamate?
Tre modi: scarica un CSV dalla pagina Calls (esporta tutti i record corrispondenti ai filtri attivi, non solo la pagina visibile), leggili tramite API con un'API key con scope voice:read, oppure usa la Bird CLI con bird voice list.
Quali eventi vocali emette Bird?
Tre: voice_call.initiated (Bird ha accettato la chiamata e avviato il routing), voice_call.answered (il numero chiamato ha risposto) e voice_call.ended (la chiamata è terminata, con l'esito). Una chiamata senza risposta non genera mai l'evento answered.
Una chiamata rifiutata genera eventi?
Una chiamata che Bird rifiuta dopo aver accettato l'INVITE termina comunque con voice_call.ended, con stato failed e sip_response_code 503. Quindi ogni chiamata di cui ricevi notifica di apertura viene anche chiusa. Una chiamata che Bird non può ammettere affatto (respinta a livello SIP) non produce alcun evento.
Gli eventi possono arrivare fuori ordine?
Sì. Le consegne non sono ordinate, quindi answered può raggiungervi dopo ended. Ordinate in base al campo timestamp e lasciate che un evento arrivato dopo con un timestamp precedente venga scartato.
Come evito di contare gli eventi due volte?
Deduplicate in base all'header HTTP webhook-id. Bird consegna almeno una volta e l'evento initiated di una chiamata può essere pubblicato più di una volta quando un retry di segnalazione lo riproduce. Stessa chiamata, stesso stadio, stesso webhook-id.
Dove si trovano il costo e il motivo del rifiuto negli eventi?
Si trovano nel record della chiamata, non nell'evento. Uno stato failed su voice_call.ended non indica se la causa è stata Bird o un operatore. Aprite la chiamata nel registro chiamate per il motivo del rifiuto; il costo compare lì una volta che la chiamata è stata tariffata.
La mia chiamata non compare nel registro chiamate. Dov'è?
Una chiamata che Bird non può ammettere viene respinta a livello SIP, prima che venga creato un record. Verifica quattro cose: il trunk ha un intervallo IP o un'API key che autorizza i tuoi dispositivi, la chiamata è arrivata da un indirizzo presente nella lista IP consentiti del trunk (dietro NAT, è l'indirizzo pubblico del router), le credenziali Digest sono corrette (username bird, il secret dell'API key giusto, un algoritmo offerto dal trunk) e il dominio SIP corrisponde esattamente al dominio del trunk.
La mia chiamata è fallita con un motivo di rifiuto. Cosa devo fare?
Apri la chiamata nel registro chiamate. Il pannello sopra i dettagli indica la causa e rimanda all'impostazione che la risolve. I sette motivi che puoi correggere sono source_not_allowed, caller_id_not_verified, destination_not_enabled, insufficient_balance, daily_spend_exceeded, concurrent_calls_exceeded e calls_per_second_exceeded.
Il mio client risponde alla challenge Digest con MD5 ma non funziona.
Alcuni dispositivi gestiscono male una challenge che inizia con SHA-256. Imposta l'algoritmo Digest del trunk su solo MD5 e il tuo PBX riceverà una challenge che può gestire.
Le chiamate si connettono ma l'audio è unidirezionale. Qual è il problema?
Il tuo client è dietro NAT (un router o firewall che riscrive gli indirizzi) e il flusso multimediale viene inviato a un indirizzo privato irraggiungibile dall'altro lato. Attiva la gestione NAT o STUN del tuo client affinché annunci il proprio indirizzo pubblico nell'offerta multimediale.
La connessione SIP è crittografata?
È possibile. Bird supporta TLS sulla porta 5061 per la segnalazione SIP, quindi la configurazione della chiamata è crittografata in transito. UDP e TCP sulla porta 5060 non sono crittografati. Scegli il trasporto in base ai tuoi requisiti di sicurezza.
Come verifico che un webhook provenga realmente da Bird?
Ogni evento è firmato con HMAC. Verifica la firma con il secret del tuo endpoint prima di elaborare il payload e ruota il secret dalla dashboard ogni volta che lo ritieni necessario.
Dove vengono archiviati i miei dati?
Nella regione in cui è ospitata la tua organizzazione, us1 o eu1. La tua API key lo indica nel prefisso (bk_us1_, bk_eu1_): è così che gli SDK e la CLI selezionano automaticamente l'endpoint corretto senza che tu debba configurarlo.
Cosa può fare un'API key utilizzata per le chiamate vocali?
Solo ciò per cui la configuri. Una key contiene un elenco di scope, ciascuno in lettura o scrittura. Una key con voice:write può autenticare le chiamate su un trunk; una key con voice:read può elencare i record delle chiamate. Una key non può accedere a canali o impostazioni al di fuori dei propri scope.
Perché una chiamata rifiutata restituisce un semplice SIP 503 senza dettagli?
Il motivo specifico viene registrato nel record della chiamata, dove solo tu puoi leggerlo. Restituire un generico 503 a livello SIP impedisce a chi tenta di sondare il tuo trunk di scoprire quali trunk, numeri e destinazioni esistono.
Dove trovo la documentazione sulla sicurezza e la protezione dei dati di Bird?
Le certificazioni e la documentazione sulla sicurezza si trovano nel Trust Center su trust.bird.com. L'accordo sul trattamento dei dati, l'informativa sulla privacy e la policy di utilizzo accettabile sono pubblicati su bird.com/legal. Per un questionario fornitore, il team del tuo account Bird se ne occupa.