Event voice

Bird mengirimkan event webhook saat panggilan dimulai, dijawab, dan berakhir. Gunakan event ini untuk memperbarui sistem Anda tanpa polling. Lihat Webhook untuk langganan, tanda tangan, percobaan ulang, dan replay.

Jalur panggilan melalui tipe event:

1. voice_call.initiated: Bird menerima permintaan penyiapan panggilan (SIP INVITE) dan mulai merutekan panggilan
2. voice_call.answered: nomor yang Anda hubungi mengangkat. Hanya panggilan yang dijawab yang mendapatkan event ini
3. voice_call.ended: panggilan selesai, dan event ini membawa hasilnya

voice_call.initiated mengonfirmasi bahwa panggilan ada, sedangkan voice_call.ended melaporkan hasilnya. Untuk panggilan yang ditolak atau gagal, gunakan status yang dilaporkan dan respons SIP akhir bersama dengan catatan panggilan. Jangan menyimpulkan siklus hidup lengkap dari keberadaan satu event saja.

Event type adalah open enum: Bird dapat menambahkan tipe baru seiring waktu, jadi cocokkan tipe yang Anda tangani dan abaikan sisanya alih-alih memperlakukan tipe yang tidak dikenal sebagai kesalahan.

Envelope event

Event voice tiba dalam envelope bersarang yang sama seperti setiap event Bird lainnya, yang dijelaskan di panduan Webhook: type, timestamp, dan objek data khusus tipe. Identitas event berada di header webhook-id HTTP, bukan di body.

data setiap event voice berisi field identitas yang sama untuk korelasi. Nomor telepon menggunakan format E.164: awalan +, kode negara, dan nomor nasional. Untuk panggilan browser ke pengguna workspace atau ring group, from dapat berupa ID usr_ pemanggil. Panggilan browser ke pengguna workspace, ring group, dan sequence masih dalam tahap pratinjau. Para pihak juga dapat berupa ekstensi SIP, dan to dapat berupa ID pengguna workspace, ring group, atau sequence.

Nama field event berbeda dari API leg: event call_id mengidentifikasi leg dan cocok dengan id pada respons leg; event session_id cocok dengan call_id pada respons leg. Gunakan pemetaan tersebut saat menggabungkan pembaruan webhook dengan catatan API.

Event siklus hidup ini menggunakan kontrak pengiriman dan tanda tangan webhook bersama. Langkah webhook sinkron dalam sequence menggunakan protokol penerima terpisah, yang ditandatangani dengan secret callback workspace, bukan dengan secret langganan event.

voice_call.initiated

Bird menerima INVITE dan mulai merutekan.

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

Penerima menjawab, dan waktu yang dapat ditagih dimulai. Panggilan yang tidak dijawab tidak mengirimkan event ini.

Payload-nya adalah field identitas panggilan yang dibawa setiap event voice, dengan timestamp diatur ke saat panggilan dijawab.

voice_call.ended

Panggilan selesai. Event ini menambahkan hasilnya:

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

Event ini tidak menyebutkan alasan panggilan berakhir. Panggilan yang mencapai batas durasi panggilan platform tiba sebagai akhir answered biasa, dengan duration_ms sekitar 4 jam.

Catatan panggilan menyimpan dua detail yang tidak disertakan event ini: alasan penolakan dan biaya. Buka panggilan di call log untuk membedakan penolakan Bird dari kegagalan operator. Biaya muncul setelah proses rating selesai.

Mengonsumsi event dengan aman

• Deduplikasi berdasarkan webhook-id. Percobaan ulang sinyal atau pengiriman dapat mengulangi pembaruan. Publikasi ulang tahap panggilan yang sama mempertahankan identitas pengirimannya, sehingga menggunakan nilai tersebut sebagai kunci akan menghilangkan duplikat.
• Jangan bergantung pada urutan. Pengiriman tidak berurutan, sehingga answered bisa sampai setelah ended. Urutkan berdasarkan timestamp, dan biarkan event yang tiba belakangan dengan timestamp lebih awal kalah.
• Gunakan ended untuk hasil yang dilaporkan. Event ini membawa status dan durasi. Publikasi event bisa gagal sebelum pengiriman diantrekan, jadi event yang tidak ada bukan berarti panggilan masih aktif.
• Rekonsiliasi dengan catatan panggilan. Event memberikan pembaruan tepat waktu, sedangkan call log menyimpan catatan panggilan. Ekspor panggilan sebagai CSV untuk rekonsiliasi.

Langkah selanjutnya