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:
- voice_call.initiated: Bird menerima permintaan penyiapan panggilan (SIP INVITE) dan mulai merutekan panggilan
- voice_call.answered: nomor yang Anda hubungi mengangkat. Hanya panggilan yang dijawab yang mendapatkan event ini
- voice_call.ended: panggilan selesai, dan event ini membawa hasilnya
voice_call.initiated mengonfirmasi bahwa panggilan ada, sedangkan voice_call.ended melaporkan hasilnya. Panggilan yang Bird ditolak setelah menerima INVITE tetap mengirimkan voice_call.ended dengan status: "failed" dan sip_response_code: 503.
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.
| Field | Deskripsi |
|---|---|
| type | Salah satu dari tiga tipe di halaman ini, misalnya voice_call.ended |
| timestamp | Kapan event terjadi (RFC 3339). Urutkan berdasarkan ini, jangan berdasarkan urutan kedatangan |
| data | Payload khusus event, selalu membawa field identitas panggilan yang sama |
data setiap event voice berisi field identitas yang sama untuk korelasi. Kedua nomor menggunakan format E.164: awalan +, kode negara, dan nomor nasional.
| Field | Deskripsi |
|---|---|
| call_id | ID catatan panggilan (vcl_…), sama seperti yang ditampilkan di Call log |
| session_id | Dibagikan oleh setiap leg panggilan yang ditransfer atau multi-pihak (vcs_…). Null jika tidak ada korelasi sesi |
| workspace_id | Workspace tempat panggilan ini berada |
| direction | outbound untuk panggilan yang dilakukan perangkat Anda |
| from | Nomor pemanggil |
| to | Nomor yang dihubungi |
voice_call.initiated
Bird menerima INVITE dan mulai merutekan.
Contoh kode
{
"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 momen jawaban.
voice_call.ended
Panggilan selesai. Event ini menambahkan hasilnya:
| Field | Deskripsi |
|---|---|
| status | Cara panggilan berakhir: answered, no_answer, failed, rejected, atau unknown (lihat Status) |
| sip_response_code | Kode SIP akhir panggilan, misalnya 200 atau 486. Panggilan yang Bird ditolak membawa 503; null jika tidak ada kode akhir yang tercatat |
| duration_ms | Total durasi panggilan dalam milidetik, dari saat Bird menerima panggilan hingga pemutusan |
| billable_ms | Waktu terjawab dalam milidetik, sehingga panggilan yang tidak dijawab melaporkan nol |
Contoh kode
{
"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
}
}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. Bird mengirim setidaknya satu kali, dan event initiated suatu panggilan dapat dipublikasikan lebih dari sekali saat signaling retry memutar ulang. Panggilan sama, tahap sama, webhook-id sama, sehingga menggunakan kunci ini menggabungkan 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.
- Perlakukan ended sebagai satu-satunya hasil yang andal. Event inilah yang membawa status dan durasi, dan event inilah yang menjadi acuan catatan Anda.
- Rekonsiliasi dengan catatan panggilan. Event memberikan pembaruan tepat waktu, sedangkan call log menyimpan catatan panggilan. Ekspor panggilan sebagai CSV untuk rekonsiliasi.
Langkah selanjutnya
| Halaman | Cakupan |
|---|---|
| Webhook & event | Penyiapan endpoint, verifikasi tanda tangan, percobaan ulang, dan replay |
| Call log | Setiap field pada catatan panggilan, dan ekspor CSV |
Sumber daya terkait
Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.