Panoramica di Voice
Bird Voice ti consente di chiamare numeri di telefono e rispondere alle chiamate verso i numeri che possiedi. Collega un sistema telefonico tramite SIP, effettua una chiamata dal browser o usa il builder di sequenze per eseguire un flusso di chiamata salvato. Bird collega le chiamate alla rete telefonica pubblica, la PSTN.
La connessione tra il tuo sistema telefonico e Bird è un trunk SIP. SIP (Session Initiation Protocol) stabilisce le chiamate tra sistemi telefonici. Bird assegna al tuo spazio di lavoro un indirizzo trunk, che il tuo sistema telefonico usa per le chiamate in uscita verso la rete telefonica, e che Bird usa in direzione opposta per consegnare le chiamate in arrivo sui tuoi numeri.
Non ti serve un sistema telefonico per effettuare la prima chiamata: il telefono nella dashboard ne avvia una direttamente dal browser, attraverso uno dei tuoi trunk.
Puoi anche creare una sequenza nella dashboard e avviarla con la API Create Call. La sequenza gestisce i messaggi vocali, le scelte da tastiera e l'instradamento della chiamata dopo che il destinatario risponde.
Come viene effettuata una chiamata
Il tuo sistema telefonico invia un SIP INVITE all'indirizzo del trunk per avviare una chiamata. Bird verifica l'ID chiamante, il paese di destinazione, i limiti e il saldo del portafoglio prima di contattare un operatore. Se la chiamata supera i controlli, Bird la instrada e trasmette l'audio. Ogni connessione è un leg. Quando un leg termina, Bird scrive il relativo record in Voice > Legs ed emette un voice_call.ended evento.
Una chiamata che non supera un controllo viene rifiutata prima che un operatore sia coinvolto, e il motivo specifico viene registrato nel record del leg. Effettuare chiamate descrive ciò che Bird legge da ogni chiamata, e Chiamate rifiutate elenca ogni motivo di rifiuto e come risolverlo.
Come si risponde a una chiamata in entrata
Ogni numero del tuo spazio di lavoro ha una sola azione alla volta per le chiamate in arrivo, impostata sul numero: consegnare la chiamata a uno dei tuoi trunk SIP, inoltrarla a un numero verificato, eseguire una sequenza pubblicata o rifiutarla. Ogni nuovo numero rifiuta inizialmente le chiamate, quindi un numero non configurato respinge i chiamanti.
Quando arriva una chiamata, Bird controlla i limiti dell'account e il wallet come per una chiamata in uscita, poi agisce in base alla risposta del numero e registra quale risposta è stata applicata. Ricevere chiamate spiega come assegnare una risposta a un numero, cosa mostra un inoltro a chi risponde e come leggere un rifiuto.
Prima della tua prima chiamata
Per le chiamate tramite la tua apparecchiatura SIP, prepara quanto segue. Per le chiamate tramite API, segui i prerequisiti di Create Call.
- Crea un trunk SIP, attiva le chiamate in uscita e autorizza i chiamanti: un intervallo IP o una chiave API per il tuo apparato, credenziali di sessione per un browser o il CLI.
- Scegli un caller ID idoneo: usa un numero che il tuo spazio di lavoro possiede tramite Bird, oppure registra un numero esterno e confermalo con una chiamata di verifica.
- Abilita le destinazioni: attiva i paesi verso cui chiami.
Effettua la tua prima chiamata ti guida attraverso tutti e tre i requisiti e termina con una chiamata reale.
Leggere i record delle chiamate richiede voice:read; effettuare chiamate richiede voice:write. La gestione di trunk, instradamenti dei numeri, caller ID e sequenze usa i permessi voice_management. L'accesso a una pagina non concede il permesso di modificarne le impostazioni né di effettuare una chiamata fatturabile.
L'app Voice nella dashboard
| Pagina | A cosa serve |
|---|---|
| Metrics | Volume delle chiamate e percentuale di risposta nel tempo, esiti delle chiamate, principali paesi e suddivisione in entrata/uscita. Vedi Metriche Voice |
| Legs | Record per leg delle chiamate dello spazio di lavoro, con i totali di utilizzo del mese |
| Calls | Leg e partecipanti correlati raggruppati in un'unica chiamata |
| Numbers | Ogni numero che lo spazio di lavoro può usare per le chiamate vocali, e cosa fa ciascuno con una chiamata in entrata |
| SIP Trunks | I tuoi trunk, il loro dominio SIP, chi può inviare traffico e dove vengono consegnate le chiamate in entrata |
| Destinations | I paesi che il tuo spazio di lavoro può chiamare, disattivati per impostazione predefinita |
| Sequences | Creare, visualizzare in anteprima e pubblicare flussi di chiamata e ispezionarne le esecuzioni |
| Phone | Un telefono flottante che effettua chiamate dal browser, attraverso uno dei tuoi trunk |
Visibilità
Una chiamata può contenere più leg. Il registro contiene un record per ogni leg, sia che la connessione sia riuscita, sia che il leg sia rimasto senza risposta o sia stato rifiutato. Le chiamate inoltrate o con più partecipanti possono quindi avere più voci:
- Log dei leg: la vista per leg nella pagina Legs. Stato, entrambi i numeri, il trunk su cui è arrivato il leg, la risposta SIP con cui si è concluso, orari di risposta e fine, tempo fatturabile e costo. Filtra i risultati, poi esportali come CSV.
- Eventi Voice: voice_call.initiated, voice_call.answered e voice_call.ended consegnati al tuo endpoint, così i tuoi sistemi vengono informati di una chiamata senza polling.
Il riferimento API elenca i contratti HTTP pubblici supportati e i metodi SDK. Il riferimento CLI e il riferimento tool MCP descrivono le operazioni pubblicate. Queste superfici possono esporre operazioni diverse; un'azione nella dashboard o un comando CLI non stabilisce di per sé un metodo SDK pubblico.
Limiti
Tre soglie si applicano alle tue chiamate, in entrambe le direzioni: quante puoi avere in corso contemporaneamente, quante nuove chiamate al secondo e quanto puoi spendere in voce in un giorno UTC. Ciascuna è impostata per organizzazione e gli importi dipendono dal tuo piano. Una chiamata che supera una qualsiasi di queste soglie viene rifiutata all'avvio, e il suo record indica quale soglia è stata superata, sotto Chiamate rifiutate.
La soglia al secondo è la policy voice_call in Limitazione delle richieste, che spiega anche come viene determinato il tuo limite effettivo e come richiedere più capacità.
Prossimi passi
| Pagina | Cosa tratta |
|---|---|
| Effettua la tua prima chiamata | Da uno spazio di lavoro vuoto a un telefono che squilla |
| Phone | Chiamare dalla dashboard, cosa serve e cosa puoi fare durante la chiamata |
| Trunk SIP | Creare un trunk, i dettagli di connessione e controllare chi può inviare traffico |
| Effettuare chiamate | Cosa si aspetta Bird sul INVITE, e quanto costa una chiamata |
| Ricevere chiamate | Associare un numero a un trunk o a un inoltro, e cosa viene registrato |
| Caller ID | Registrare un numero e dimostrarne la titolarità con una chiamata di verifica |
| Destinazioni Voice | Attivare i paesi verso cui chiami e cosa significa rischio elevato |
| Log dei leg | Consultazione, filtraggio ed esportazione dei record dei leg |
| Eventi Voice | I tre eventi di chiamata e i relativi payload |
| Risoluzione dei problemi | Diagnosticare una chiamata che non va a buon fine, partendo dal sintomo |
| Webhook ed eventi | Configurazione dell'endpoint, verifica della firma, ripetizioni e replay |
Risorse correlate
Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.