Zdarzenia głosowe
Bird emituje zdarzenia webhook, gdy połączenie się rozpoczyna, zostaje odebrane i kończy. Używaj ich do aktualizacji swoich systemów bez odpytywania. Szczegóły dotyczące subskrypcji, sygnatur, ponowień i odtwarzania znajdziesz w sekcji Webhooki.
Ścieżka połączenia przez typy zdarzeń:
- voice_call.initiated: Bird przyjął żądanie zestawienia połączenia (SIP INVITE) i rozpoczął trasowanie połączenia
- voice_call.answered: wywoływany numer odebrał. Tylko odebrane połączenia generują to zdarzenie
- voice_call.ended: połączenie się zakończyło, a zdarzenie zawiera wynik
voice_call.initiated potwierdza, że połączenie istnieje, a voice_call.ended raportuje jego wynik. W przypadku odrzuconego lub nieudanego połączenia użyj zgłoszonego statusu i końcowej odpowiedzi SIP razem z rekordem połączenia. Nie wnioskuj o pełnym cyklu życia na podstawie obecności jednego zdarzenia.
Zdarzenie type to otwarty enum: Bird może z czasem dodawać nowe typy, więc obsługuj te, które rozpoznajesz, a pozostałe ignoruj, zamiast traktować nieznany typ jako błąd.
Koperta zdarzenia
Zdarzenia głosowe przychodzą w tej samej zagnieżdżonej kopercie co każde inne zdarzenie Bird, opisanej w przewodniku po webhookach: type, timestamp oraz obiekt data specyficzny dla danego typu. Tożsamość zdarzenia znajduje się w nagłówku webhook-id HTTP, a nie w treści.
| Pole | Opis |
|---|---|
| type | Jeden z trzech typów na tej stronie, na przykład voice_call.ended |
| timestamp | Kiedy zdarzenie wystąpiło (RFC 3339). Sortuj po tym polu, nigdy po kolejności dostarczenia |
| data | Ładunek specyficzny dla zdarzenia, zawsze zawierający te same pola identyfikujące połączenie |
Pole data każdego zdarzenia głosowego zawiera te same pola identyfikujące, służące do korelacji. Oba numery używają formatu E.164: wiodący +, kod kraju i numer krajowy.
| Pole | Opis |
|---|---|
| call_id | Identyfikator rekordu połączenia (vcl_…), ten sam, który widnieje w Logu połączeń |
| session_id | Współdzielony przez każdą odnogę przekierowanego lub wielostronnego połączenia (vcs_…). Null, gdy korelacja sesji nie ma zastosowania |
| workspace_id | Obszar roboczy, do którego należy połączenie |
| direction | inbound dla połączeń przychodzących; outbound dla połączeń wychodzących |
| from | Numer dzwoniącego |
| to | Wywoływany numer |
voice_call.initiated
Bird odebrał INVITE i rozpoczął trasowanie.
Przykład kodu
{
"type": "voice_call.initiated",
"timestamp": "2026-06-10T14:30:00Z",
"data": {
"call_id": "vcl_01krdgeqcxet5s7t44vh8rt9mg",
"session_id": "vcs_01krdgeqcxet5s7t44vh8rt9mh",
"workspace_id": "wsp_01krdgeqcxet5s7t44vh8rt9mj",
"direction": "outbound",
"from": "+14155551234",
"to": "+16505559876"
}
}voice_call.answered
Odbiorca odebrał i rozpoczął się czas podlegający rozliczeniu. Nieodebrane połączenie nie generuje tego zdarzenia.
Ładunek to pola identyfikujące połączenie, które zawiera każde zdarzenie głosowe, z timestamp ustawionym na moment odebrania.
voice_call.ended
Połączenie się zakończyło. To zdarzenie dodaje wynik:
| Pole | Opis |
|---|---|
| status | Sposób zakończenia: answered, no_answer, failed, rejected lub unknown (zobacz Statusy) |
| sip_response_code | Końcowy kod SIP połączenia, na przykład 200 lub 486. Połączenie odrzucone przez Bird ma kod 503; null, gdy nie zarejestrowano kodu końcowego |
| duration_ms | Całkowity czas połączenia w milisekundach, od momentu otrzymania żądania połączenia przez Bird do rozłączenia |
| billable_ms | Czas rozmowy w milisekundach, więc połączenie, którego nikt nie odebrał, zwraca zero |
Przykład kodu
{
"type": "voice_call.ended",
"timestamp": "2026-06-10T14:31:05Z",
"data": {
"call_id": "vcl_01krdgeqcxet5s7t44vh8rt9mg",
"session_id": "vcs_01krdgeqcxet5s7t44vh8rt9mh",
"workspace_id": "wsp_01krdgeqcxet5s7t44vh8rt9mj",
"direction": "outbound",
"from": "+14155551234",
"to": "+16505559876",
"status": "answered",
"sip_response_code": 200,
"duration_ms": 65000,
"billable_ms": 60000
}
}Rekord połączenia zawiera dwa szczegóły, których to zdarzenie nie uwzględnia: powód odrzucenia i koszt. Otwórz połączenie w logu połączeń, aby odróżnić odrzucenie Bird od awarii operatora. Koszt pojawia się po zakończeniu taryfikacji.
Bezpieczna konsumpcja zdarzeń
- Deduplikuj po webhook-id. Ponowna próba sygnalizacji lub dostarczenia może powtórzyć aktualizację. Ponowna publikacja tego samego etapu połączenia zachowuje tożsamość dostarczenia, więc klucz oparty na niej eliminuje duplikat.
- Nie polegaj na kolejności. Dostarczenia nie są uporządkowane, więc answered może dotrzeć do ciebie po ended. Sortuj po timestamp i pozwól, aby zdarzenie dostarczone później z wcześniejszym znacznikiem czasu przegrało.
- Używaj ended dla zgłoszonego wyniku. Zawiera status i czasy trwania. Publikacja zdarzenia może się nie powieść, zanim dostarczenie zostanie zakolejkowane, więc brak zdarzenia nie oznacza, że połączenie jest nadal aktywne.
- Uzgadniaj z rekordami połączeń. Zdarzenia dostarczają bieżące aktualizacje, natomiast log połączeń przechowuje rekord połączenia. Eksportuj połączenia jako CSV do uzgodnień.
Następne kroki
| Strona | Co obejmuje |
|---|---|
| Webhooki i zdarzenia | Konfiguracja endpointu, weryfikacja sygnatury, ponowienia i odtwarzanie |
| Log połączeń | Wszystkie pola rekordu połączenia i eksport CSV |
Powiązane zasoby
Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.