Eventi vocali

Bird emette eventi webhook quando una chiamata inizia, riceve risposta e termina. Usali per aggiornare i tuoi sistemi senza polling. Consulta Webhook per sottoscrizioni, firme, tentativi e replay.

Il percorso di una chiamata attraverso i tipi di evento:

voice_call.initiated: Bird ha accettato la richiesta di impostazione della chiamata (una SIP INVITE) e ha iniziato l'instradamento
voice_call.answered: il numero chiamato ha risposto. Solo le chiamate con risposta ricevono questo evento
voice_call.ended: la chiamata è terminata e l'evento contiene l'esito

voice_call.initiated conferma che una chiamata esiste, mentre voice_call.ended ne riporta l'esito. Per una chiamata rifiutata o fallita, usa lo stato riportato e la risposta SIP finale insieme al registro della chiamata. Non dedurre un ciclo di vita completo dalla presenza di un singolo evento.

Il type dell'evento è un open enum: Bird può aggiungere tipi nel tempo, quindi gestisci quelli che ti servono e ignora il resto invece di trattare un tipo sconosciuto come errore.

L'envelope dell'evento

Gli eventi vocali arrivano nello stesso envelope annidato di ogni altro evento Bird, descritto nella guida ai Webhook: type, timestamp e un oggetto data specifico per tipo. L'identità dell'evento è nell'header webhook-id HTTP, non nel body.

Campo	Descrizione
type	Uno dei tre tipi presenti in questa pagina, ad esempio voice_call.ended
timestamp	Quando si è verificato l'evento (RFC 3339). Ordina per questo campo, mai per ordine di arrivo
data	Payload specifico dell'evento, che contiene sempre gli stessi campi di identità della chiamata

Il data di ogni evento vocale contiene gli stessi campi di identità per la correlazione. Entrambi i numeri usano il formato E.164: un + iniziale, il prefisso del paese e il numero nazionale.

Campo	Descrizione
call_id	L'id del record della chiamata (vcl_…), lo stesso mostrato nel Registro chiamate
session_id	Condiviso da ogni segmento di una chiamata trasferita o multipartecipante (vcs_…). Null quando non si applica alcuna correlazione di sessione
workspace_id	Lo spazio di lavoro a cui appartiene la chiamata
direction	inbound per le chiamate ricevute; outbound per le chiamate effettuate
from	Il numero chiamante
to	Il numero chiamato

voice_call.initiated

Bird ha ricevuto la INVITE e ha iniziato l'instradamento.

Esempio di codice

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

Il destinatario ha risposto e il tempo fatturabile è iniziato. Una chiamata senza risposta non emette questo evento.

Il payload corrisponde ai campi di identità della chiamata presenti in ogni evento vocale, con timestamp impostato al momento della risposta.

voice_call.ended

La chiamata è terminata. Questo evento aggiunge l'esito:

Campo	Descrizione
status	Come è terminata: answered, no_answer, failed, rejected o unknown (vedi Stati)
sip_response_code	Il codice SIP finale della chiamata, ad esempio 200 o 486. Una chiamata rifiutata da Bird riporta 503; null quando non è stato registrato alcun codice finale
duration_ms	Durata totale della chiamata in millisecondi, dal momento in cui Bird ha ricevuto la chiamata fino al riaggancio
billable_ms	Tempo di conversazione in millisecondi; una chiamata senza risposta riporta zero

Esempio di codice

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

Il record della chiamata contiene due dettagli che questo evento non include: il motivo del rifiuto e il costo. Apri la chiamata nel registro chiamate per distinguere un rifiuto Bird da un errore dell'operatore. Il costo compare al termine della tariffazione.

Consumarli in sicurezza

Deduplica in base a webhook-id. Un nuovo tentativo di segnalazione o consegna può ripetere un aggiornamento. La ripubblicazione dello stesso stadio di chiamata mantiene la sua identità di consegna, quindi usarla come chiave elimina il duplicato.
Non fare affidamento sull'ordine. Le consegne non sono ordinate, quindi answered può arrivarti dopo ended. Ordina per timestamp e lascia che un evento arrivato dopo con un timestamp precedente venga scartato.
Usa ended per l'esito riportato. Contiene stato e durate. La pubblicazione dell'evento può fallire prima che la consegna venga accodata, quindi un evento mancante non significa che la chiamata sia ancora attiva.
Riconcilia con i record delle chiamate. Gli eventi forniscono aggiornamenti tempestivi, mentre il registro chiamate conserva il record della chiamata. Esporta le chiamate in CSV per la riconciliazione.

Prossimi passi

Pagina	Argomenti trattati
Webhook ed eventi	Configurazione dell'endpoint, verifica della firma, tentativi e replay
Registro chiamate	Tutti i campi di un record della chiamata ed esportazione CSV

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Comprendi il concettoWhat is a voice API?Esplora la funzionalitàVoice Guida all'implementazioneVoice overview

Ottieni un brief di implementazione