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ń:

1. voice_call.initiated: Bird przyjął żądanie zestawienia połączenia (SIP INVITE) i rozpoczął trasowanie połączenia
2. voice_call.answered: wywoływany numer odebrał. Tylko odebrane połączenia generują to zdarzenie
3. 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 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.

Nazwy pól zdarzenia różnią się od API odnogi: pole call_id zdarzenia identyfikuje odnogę i odpowiada polu id w odpowiedzi odnogi; pole session_id zdarzenia odpowiada polu call_id w odpowiedzi odnogi. Korzystaj z tego mapowania, łącząc aktualizacje webhook z rekordami API.

Te zdarzenia cyklu życia korzystają ze współdzielonego kontraktu dostarczania i sygnowania webhooków. Synchroniczny krok webhook w sekwencji używa osobnego, niepodpisanego protokołu odbiorcy; skonfigurowanie subskrypcji zdarzenia nie uwierzytelnia żądań z tego kroku.

voice_call.initiated

Bird odebrał INVITE i rozpoczął trasowanie.

{
  "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:

{
  "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
  }
}

To zdarzenie nie wskazuje przyczyny zakończenia połączenia. Połączenie, które osiągnęło limit czasu trwania platformy, dociera jako zwykłe zakończenie answered z duration_ms wynoszącym około 3 godzin.

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