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. Una chiamata che Bird rifiuta dopo aver accettato la INVITE emette comunque voice_call.ended con status: "failed" e sip_response_code: 503.

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	outbound per le chiamate effettuate dal tuo apparato
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 Bird rifiutata 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. Bird consegna almeno una volta, e l'evento initiated di una chiamata può essere pubblicato più di una volta quando un tentativo di segnalazione viene ripetuto. Stessa chiamata, stesso stadio, stesso webhook-id: usarlo 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.
Considera ended come l'unico esito affidabile. È l'evento che contiene lo stato e le durate, ed è quello su cui basare i tuoi record.
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