FAQ Voice API

Bird Voice umożliwia wykonywanie połączeń na numery telefonów przez trunk SIP. Twój system telefoniczny łączy się z Bird, a Bird przekierowuje każde połączenie przez operatora do publicznej sieci telefonicznej (PSTN). Ty zapewniasz własną centralę PBX lub softphone; Bird obsługuje połączenie po stronie operatora.

Około dziesięciu minut. Utwórz trunk SIP, zweryfikuj identyfikator dzwoniącego, włącz kraj docelowy i skieruj swój system telefoniczny na adres trunku. Przewodnik po pierwszym połączeniu przeprowadzi Cię przez cały proces.

Trzy rzeczy po Twojej stronie: trunk SIP z autoryzacją Twojego sprzętu (według zakresu IP lub klucza API), zweryfikowany identyfikator dzwoniącego (numer, który prezentujesz jako dzwoniący) oraz włączony kraj docelowy. Bird przypisuje routing do Twojego workspace — to czwarty warunek, realizowany po stronie Bird.

Nie. Wystarczy dowolny system telefoniczny obsługujący SIP: softphone, taki jak Zoiper lub Linphone na laptopie, centrala PBX, taka jak Asterisk lub FreeSWITCH, albo system komercyjny, taki jak 3CX lub FreePBX. Bird przydziela Ci domenę SIP, a Ty kierujesz na nią swój sprzęt.

Tak. Możesz wykonywać połączenia z aplikacji Phone w panelu, korzystając z WebRTC.

Za połączenie, według stawki zależnej od kraju docelowego. Każda stawka ma przyrost rozliczeniowy: minimalny czas naliczany, a następnie krok, do którego jest zaokrąglany. Stawka z jednominutowym minimum i sześciosekundowymi krokami naliczy za 10-sekundowe połączenie pełną minutę.

Czas rozliczeniowy biegnie od momentu odebrania połączenia przez wywoływany numer do momentu zakończenia połączenia. Czas dzwonienia nie jest naliczany, więc połączenie, którego nikt nie odbierze, nic nie kosztuje.

Przedpłacone, z portfela Twojej organizacji. Bird sprawdza saldo przed wybraniem numeru przez operatora, więc połączenie, na które nie wystarcza środków, jest odrzucane z góry z powodu insufficient_balance, zamiast być rozliczane po fakcie.

Tak. Dla każdej organizacji obowiązuje dzienny limit wydatków na połączenia głosowe, który resetuje się na początku każdego dnia UTC. Po jego przekroczeniu połączenia są odrzucane z kodem daily_spend_exceeded. Kwota zależy od Twojego planu, a Bird może ją podnieść na życzenie.

Otwórz połączenie w rejestrze połączeń. Koszt pojawia się w rekordzie po jego wycenie, z pełną precyzją, bez podatku. Aby zobaczyć sumy dla wielu połączeń, wyeksportuj przefiltrowaną listę połączeń jako CSV ze strony Calls lub sprawdź faktury i zużycie.

Trzy pułapy: ile połączeń możesz prowadzić jednocześnie (połączenia równoległe), ile nowych połączeń możesz rozpocząć na sekundę (połączenia na sekundę) oraz ile możesz wydać na głos w ciągu dnia UTC (dzienny limit wydatków). Każdy jest ustawiany na organizację, a wartości zależą od Twojego planu.

Połączenie jest odrzucane na etapie zestawiania, zanim operator zostanie wybrany. Rekord połączenia wskazuje, który limit został osiągnięty: concurrent_calls_exceeded, calls_per_second_exceeded lub daily_spend_exceeded. Twój system telefoniczny otrzymuje SIP 503.

Tak. Skontaktuj się z pomocą techniczną, aby poprosić o wyższy limit połączeń równoległych lub połączeń na sekundę. Dzienny limit wydatków zależy od Twojego planu i również może zostać podniesiony.

Sprawdź, jaki powód wskazuje rekord połączenia. Dialer może osiągnąć calls_per_second_exceeded, będąc daleko od limitu połączeń równoległych, ponieważ te dwa limity są niezależne. Zmniejsz szybkość wybierania i ponów próbę; natychmiastowe ponowienie daje tę samą odpowiedź.

Trunk SIP to połączenie między Twoim systemem telefonicznym a Bird. SIP (Session Initiation Protocol) to protokół, którym systemy telefoniczne komunikują się w celu zestawiania połączeń, a trunk to linia, po której te połączenia przechodzą. Bird przydziela Twojemu workspace'owi adres trunku, a Ty kierujesz na niego swój system telefoniczny.

Większość workspace'ów potrzebuje tylko jednego. Utwórz więcej, gdy chcesz mieć osobne reguły dostępu per lokalizacja lub per system, ponieważ lista dozwolonych adresów IP, dozwolone klucze API i ustawienia Digest są konfigurowane osobno dla każdego trunku.

Domena SIP trunka (skopiowana ze strony trunka), nazwa użytkownika bird oraz hasło (sekret klucza API uprawnionego do korzystania z trunka). Wysyłaj połączenia na domenę SIP na porcie 5060 (UDP lub TCP) lub 5061 (TLS).

Tak, za pomocą listy dozwolonych adresów IP, dozwolonych kluczy API lub obu jednocześnie. Dodaj publiczne adresy, z których Twoje urządzenia wysyłają SIP, lub wymagaj uwierzytelniania każdego połączenia kluczem API przez SIP Digest. Oba ustawienia zaczynają obowiązywać od następnego połączenia.

Domena SIP trunku natychmiast przestaje przyjmować nowe połączenia. Połączenia już trwające są kontynuowane, a rekordy połączeń wykonanych przez ten trunk pozostają w rejestrze połączeń.

Twoja centrala PBX wysyła połączenie, Bird odpowiada wyzwaniem 407, a centrala ponownie wysyła połączenie z nagłówkiem Proxy-Authorization obliczonym na podstawie nazwy użytkownika bird i sekretu Twojego klucza API jako hasła. Centrala wysyła hash hasła, nigdy samo hasło.

SHA-256 i MD5. Bird oferuje domyślnie SHA-256 jako pierwszy i MD5 jako drugi, a Twoja centrala PBX wybiera pierwszy, który obsługuje. Jeśli Twój sprzęt obsługuje tylko MD5 i nieprawidłowo przetwarza wyzwanie zaczynające się od SHA-256, ustaw trunk wyłącznie na MD5.

Tak. Gdy trunk ma oba mechanizmy, adres źródłowy jest sprawdzany przed wyzwaniem Bird o hasło, więc połączenie z nieujętego na liście adresu jest odrzucane niezależnie od przesłanych poświadczeń.

Najpierw dodaj nowy klucz do trunka, przenieś swój sprzęt, a następnie unieważnij stary klucz. Unieważnienie lub usunięcie klucza natychmiast odbiera mu możliwość uwierzytelniania na każdym trunku, który go dopuszczał.

Identyfikator dzwoniącego to numer telefonu, który Twój workspace może prezentować jako numer dzwoniącego w połączeniach wychodzących. Bird sprawdza numer dzwoniącego, który Twój sprzęt umieszcza w nagłówku SIP From, porównując go z tą listą przy każdym połączeniu — połączenia wychodzą tylko z numerów, które zostały zweryfikowane.

Dodaj numer na stronie Numbers w formacie E.164. Bird natychmiast wykonuje połączenie weryfikacyjne na ten numer. Odbierz połączenie, wysłuchaj sześciocyfrowego kodu i wprowadź go w panelu. Masz pięć prób, a numer staje się dostępny do użycia, gdy tylko jedna z nich zostanie zaakceptowana.

Jeśli próby się wyczerpały, użyj opcji Get a new code w wierszu danego numeru, aby otrzymać nowe połączenie weryfikacyjne. Jeśli numer wciąż oczekuje na kod, usuń identyfikator dzwoniącego i dodaj numer ponownie.

Przekieruj go na telefon, który możesz odebrać na czas trwania weryfikacji, a potem przywróć ustawienia. W przypadku numeru, który w ogóle nie odbiera połączeń, skontaktuj się ze wsparciem technicznym.

Od tego momentu każde połączenie prezentujące ten numer jest odrzucane z błędem caller_id_not_verified. Połączenia już w toku są kontynuowane, a zapisy połączeń, które używały tego numeru, pozostają bez zmian.

Oszustwa telekomunikacyjne polegają na wybieraniu drogich krajów, do których nigdy nie zamierzałeś dzwonić. Włączone kraje to te, w których możesz generować koszty — wyłączenie pozostałych ogranicza Twoje ryzyko w przypadku włamania do systemu telefonicznego.

Znajdź kraj na stronie Destinations za pomocą pola wyszukiwania (wyszukuje po nazwie lub dwuliterowym kodzie) i przełącz jego przełącznik. Zmiana obowiązuje od tego momentu.

Połączenia do krajów wysokiego ryzyka są drogie, a operator numeru, na który dzwonisz, otrzymuje część kosztów. To kraje, które atakujący obiera za cel po włamaniu do systemu telefonicznego. Pozostaw je wyłączone, chyba że prowadzisz tam działalność, i sprawdź stawkę przed włączeniem.

Skontaktuj się ze wsparciem technicznym, aby odblokować go dla Twojego konta. Available oznacza, że możesz go włączyć; Not supported oznacza, że Bird nie może obecnie realizować połączeń do tego kraju z Twojego konta.

Dostępny kraj może nadal zawierać konkretne kierunki, do których routing jeszcze nie dociera. Wyślij ID połączenia do wsparcia technicznego, a rozszerzą routing, aby je objąć.

Dwóch nagłówków: To (wywoływany numer) i From (numer, który prezentujesz jako dzwoniący — musi to być zweryfikowany identyfikator dzwoniącego). Oba muszą być pełnymi numerami międzynarodowymi w formacie E.164: znak + na początku, kod kraju i numer krajowy. Nie są potrzebne żadne niestandardowe nagłówki.

STIR/SHAKEN to podpis, którego operatorzy używają przy podejmowaniu decyzji, czy przepuścić połączenie bez oznaczenia. Połączenia do Stanów Zjednoczonych i Francji mają go automatycznie, bez konieczności konfiguracji. Domyślnie połączenia mają poziom B; poziom A (najsilniejszy) jest dostępny na życzenie.

Otwórz połączenie w dzienniku połączeń. Twój system telefoniczny widzi zwykły SIP 503, ale konkretny powód trafia do rekordu połączenia, gdzie tylko Ty możesz go odczytać. Panel nad szczegółami wskazuje przyczynę i prowadzi do ustawienia, które ją naprawia.

Dopiero gdy przyczyna zostanie usunięta. Połączenie odrzucone z powodu calls_per_second_exceeded otrzyma tę samą odpowiedź, dopóki nie zmniejszysz szybkości wybierania. Przeczytaj powód odrzucenia przed ponowieniem próby.

Pięć: Answered (numer docelowy odebrał), No answer (dzwoniło bez odpowiedzi), Failed (połączenie nie zostało zrealizowane — Bird je odrzucił lub operator je nie obsłużył), Rejected (operator odrzucił połączenie wprost) i Unknown (nie udało się ustalić wyniku).

Oba pojawiają się jako Failed. Rozróżnia je powód odrzucenia: tylko odmowa Bird go zawiera. Nieudane połączenie z powodem odrzucenia wskazuje na ustawienie po Twojej stronie lub po stronie Bird; połączenie bez powodu odrzucenia zwykle wskazuje na wybierany numer.

Tak. Zakładka Live na stronie Calls wyświetla aktualnie trwające połączenia na Twoich trunkach wraz z liczbą. Połączenie na żywo jest wyświetlane jako Ringing (oczekiwanie na odebranie przez drugą stronę) lub In progress (połączone). Zakładka odświeża się co kilka sekund.

Całkowity czas trwania biegnie od momentu odebrania połączenia przez Bird do rozłączenia. Czas rozliczeniowy biegnie od momentu odebrania do rozłączenia. Różnica to czas dzwonienia, gdy nikt nie odebrał — duża różnica jest warta przyjrzenia się, co wybierasz. Połączenie, którego nikt nie odebrał, nic nie kosztuje.

Na trzy sposoby: pobierz CSV ze strony Calls (eksportuje wszystkie rekordy pasujące do bieżących filtrów, nie tylko widoczną stronę), odczytaj je przez API za pomocą klucza API z uprawnieniem voice:read lub użyj Bird CLI poleceniem bird voice list.

Trzy: voice_call.initiated (Bird zaakceptował połączenie i rozpoczął routing), voice_call.answered (numer docelowy odebrał) i voice_call.ended (połączenie zakończone, wraz z wynikiem). Połączenie bez odpowiedzi nigdy nie emituje zdarzenia answered.

Połączenie, które Bird odrzuca po zaakceptowaniu INVITE, nadal kończy się zdarzeniem voice_call.ended ze statusem failed i sip_response_code 503. Każde połączenie, o którego otwarciu zostaniesz poinformowany, zostanie również zamknięte. Połączenie, którego Bird w ogóle nie może przyjąć (odrzucone na warstwie SIP), nie generuje żadnych zdarzeń.

Tak. Dostarczanie nie jest uporządkowane, więc zdarzenie answered może dotrzeć do Ciebie po ended. Sortuj według pola timestamp i pozwól, aby później dostarczone zdarzenie z wcześniejszym znacznikiem czasu zostało odrzucone.

Deduplikuj na podstawie nagłówka HTTP webhook-id. Bird dostarcza co najmniej raz, a zdarzenie initiated połączenia może zostać opublikowane więcej niż raz, gdy powtórka sygnalizacyjna je odtworzy. To samo połączenie, ten sam etap, ten sam webhook-id.

Znajdują się w rekordzie połączenia, nie w zdarzeniu. Status failed w voice_call.ended nie informuje, czy spowodował go Bird, czy operator. Otwórz połączenie w dzienniku połączeń, aby zobaczyć powód odrzucenia — koszt pojawia się tam po wycenieniu połączenia.

Połączenie, którego Bird nie może przyjąć, jest odrzucane na warstwie SIP, zanim powstanie rekord. Sprawdź cztery rzeczy: trunk ma zakres IP lub klucz API zezwalający Twojemu urządzeniu, połączenie przyszło z adresu na liście dozwolonych IP trunku (za NAT jest to publiczny adres routera), dane uwierzytelniające Digest są poprawne (nazwa użytkownika bird, właściwy sekret klucza API, algorytm oferowany przez trunk) oraz domena SIP dokładnie odpowiada domenie trunku.

Otwórz połączenie w rejestrze połączeń. Panel nad szczegółami wskazuje przyczynę i zawiera link do ustawienia, które ją rozwiązuje. Siedem przyczyn, które możesz naprawić, to: source_not_allowed, caller_id_not_verified, destination_not_enabled, insufficient_balance, daily_spend_exceeded, concurrent_calls_exceeded i calls_per_second_exceeded.

Niektóre urządzenia nieprawidłowo obsługują wyzwanie rozpoczynające się od SHA-256. Ustaw algorytm Digest trunku na wyłącznie MD5, a Twoja centrala PBX otrzyma wyzwanie, które rozumie.

Twój klient jest za NAT (routerem lub firewallem, który przepisuje adresy) i media trafiają na prywatny adres, do którego druga strona nie może dotrzeć. Włącz obsługę NAT lub STUN w swoim kliencie, aby ogłaszał swój publiczny adres w ofercie mediów.

Może być. Bird obsługuje TLS na porcie 5061 dla sygnalizacji SIP, więc zestawienie połączenia jest szyfrowane podczas transmisji. UDP i TCP na porcie 5060 nie są szyfrowane. Wybierz transport odpowiadający Twoim wymaganiom bezpieczeństwa.

Każde zdarzenie jest podpisywane HMAC. Zweryfikuj podpis za pomocą sekretu swojego endpointu przed przetworzeniem danych i rotuj ten sekret z poziomu dashboardu, kiedy zajdzie taka potrzeba.

W regionie, w którym hostowana jest Twoja organizacja — us1 lub eu1. Twój klucz API niesie tę informację w swoim prefiksie (bk_us1_, bk_eu1_), dzięki czemu SDK i CLI automatycznie wybierają właściwy endpoint bez konieczności konfiguracji.

Tylko to, do czego go upoważnisz. Klucz zawiera listę zakresów (scopes), każdy na poziomie odczytu lub zapisu. Klucz z voice:write może uwierzytelniać połączenia na trunku; klucz z voice:read może wyświetlać rekordy połączeń. Klucz nie ma dostępu do kanałów ani ustawień poza swoimi zakresami.

Konkretna przyczyna trafia do rekordu połączenia, gdzie tylko Ty możesz ją odczytać. Zwracanie ogólnego 503 na warstwie SIP uniemożliwia osobie sondującej Twój trunk poznanie, jakie trunki, numery i kierunki istnieją.

Certyfikaty i dokumentacja bezpieczeństwa znajdują się w Trust Center pod adresem trust.bird.com. Umowa o przetwarzanie danych, polityka prywatności i zasady dopuszczalnego użytkowania są opublikowane na bird.com/legal. W przypadku ankiety dla dostawców zajmuje się tym Twój zespół opiekuna konta w Bird.