Katalog Peristiwa - ThunderPhone

Setiap body webhook memiliki field type yang nilainya adalah salah satu jenis peristiwa di halaman ini. Saat Anda berlangganan ke sebuah endpoint, array events harus berisi jenis peristiwa yang Anda inginkan (atau kosong untuk berlangganan ke semuanya). Dua gaya pengiriman membawa peristiwa ini:

Pengiriman endpoint selalu berupa notifikasi non-blocking dengan percobaan ulang: respons dengan 2xx apa pun; envelope membawa event_id untuk deduplikasi.
Pertukaran blocking hanya berjalan pada webhook URL tunggal lama: permintaan konfigurasi telephony.incoming / web.incoming (nomor mode webhook dan kunci widget, batas waktu 10 dtk) serta pengiriman tool mode webhook. Respons Anda membentuk panggilan langsung.

Payload contoh di bawah menunjukkan envelope endpoint dalam urutan wire-nya (kunci diurutkan secara alfabetis: data, event_id, type); pengiriman lama membawa data yang sama tanpa event_id.

Event panggilan

`telephony.incoming`

Dikirim ketika panggilan masuk mencapai salah satu nomor telepon Anda. Pengiriman ke endpoint adalah notifikasi fire-and-forget yang dikirim untuk setiap panggilan masuk, baik nomor tersebut dikonfigurasi untuk agen maupun webhook. Nomor tanpa agen yang ditetapkan juga menerima permintaan konfigurasi pemblokiran pada webhook lama — lihat telephony.incoming / web.incoming untuk skema permintaan / respons lengkap.

{
  "data": {
    "call_id": 987654321,
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  },
  "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11",
  "type": "telephony.incoming"
}

`telephony.complete`

Dikirim ketika panggilan telepon masuk atau keluar berakhir. Non-pemblokiran. Mencakup transkrip lengkap, URL rekaman, dan ringkasan penagihan. Lihat telephony.complete / web.complete untuk skema payload.

`telephony.tool`

Dikirim setelah panggilan telepon memanggil function tool. Notifikasi audit non-pemblokiran — tool telah dijalankan saat event ini dikirimkan; event ini mencakup function tool Anda sendiri (bukan tool bawaan, basis pengetahuan, koneksi aplikasi, atau MCP).

{
  "data": {
    "arguments": { "date": "2026-04-21" },
    "call_id": 987654321,
    "from_number": "+14155550199",
    "response": {
      "response": { "available_slots": ["9:00 AM", "2:00 PM"] },
      "status": 200
    },
    "to_number": "+15551234567",
    "tool_name": "search_appointments"
  },
  "event_id": "1f0a7c3e-52d4-4a0e-8f4b-b1a6a1c0d9e2",
  "type": "telephony.tool"
}

response adalah hasil yang dijalankan: {"status": <http status>, "response": <your endpoint's JSON>} saat berhasil, atau {"status": <status>, "error": "<message>"} saat gagal.

`web.incoming`

Setara kanal web untuk telephony.incoming, dikirim ketika sesi widget web atau panggilan uji mic builder dimulai. Pengiriman ke endpoint adalah fire-and-forget untuk setiap sesi web. Publishable key dalam mode="webhook" juga menerima permintaan konfigurasi pemblokiran pada webhook lama — permintaan pemblokiran tersebut memiliki bentuk berbeda (origin_domain, publishable_key_prefix; tanpa nomor telepon). Lihat telephony.incoming / web.incoming.

{
  "data": {
    "call_id": 987654322,
    "from_number": "web",
    "origin_domain": "https://example.com",
    "publishable_key_prefix": "pk_live_a1b2",
    "to_number": "+15551234567"
  },
  "event_id": "9a2b4c6d-8e0f-4a1b-9c2d-3e4f5a6b7c8d",
  "type": "web.incoming"
}

from_number selalu berupa literal "web". Untuk sesi widget dalam mode webhook, to_number kosong (nomor agen sesi ditetapkan setelah konfigurasi); untuk panggilan uji mic builder, origin_domain dan publishable_key_prefix kosong.

`web.complete`

Setara kanal web untuk telephony.complete, mencakup panggilan widget web (direction: "web") dan panggilan uji mic builder (direction: "test"). Non-pemblokiran. Bentuk payload sama seperti telephony.complete, ditambah origin_domain, dengan from_number diatur ke "web".

Pada webhook lama dengan satu URL, panggilan uji mic builder secara historis dilaporkan sebagai telephony.complete — hanya panggilan direction: "web" yang menggunakan tipe web.complete di sana. Sistem endpoint memetakan panggilan web dan uji ke web.*. Payload historis dapat berisi nilai direction lama widget atau mic.

`web.tool`

Setara kanal web untuk telephony.tool. data memuat origin_domain alih-alih from_number / to_number.

Event kualitas

`call.graded`

Dikirim setiap kali proses penilaian AI selesai untuk sebuah panggilan. Tidak memblokir.

{
  "data": {
    "call_id": 987654321,
    "grade": {
      "call_outcome": "success",
      "created_at": "2026-04-20T18:25:11.002Z",
      "detected_issues": [],
      "graded_at": "2026-04-20T18:25:11.002Z",
      "grader_model": "heuristic-v1",
      "id": 5512,
      "score": 92,
      "status": "completed",
      "summary": "Caller asked about their policy and got a full answer…"
    }
  },
  "event_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "type": "call.graded"
}

Bidang	Tipe	Deskripsi
`grade.id`	integer	ID penilaian
`grade.score`	integer \| null	0–100
`grade.call_outcome`	string	`success`, `failure`, `unknown`, atau `no_conversation`
`grade.summary`	string	Ringkasan satu paragraf
`grade.detected_issues`	array	String masalah yang ditemukan oleh penilai
`grade.status`	string	Selalu `completed` — hanya proses yang selesai yang mengirim event
`grade.grader_model`	string	Penilai yang menghasilkan hasil (misalnya `heuristic-v1`)
`grade.graded_at`, `grade.created_at`	timestamp

Sebuah panggilan dapat dinilai lebih dari sekali — penilaian heuristik cepat sering diikuti oleh penilaian model lengkap setelah rekaman tersedia, dan penilaian ulang manual dimungkinkan. Setiap proses yang selesai mengirim event call.graded sendiri; anggap graded_at terbaru sebagai rujukan.

`issue.reported`

Dikirim saat laporan masalah dibuat — baik diajukan oleh pengguna dari dasbor (source: "user") maupun secara otomatis oleh penilaian panggilan (source: "system"). Tidak memblokir.

{
  "data": {
    "call_id": 987654321,
    "issue_report": {
      "created_at": "2026-04-20T18:25:11.002Z",
      "description": "Five-second silence before responding to the main question.",
      "id": 4321,
      "severity": "warning",
      "source": "system",
      "status": "open",
      "title": "Agent paused too long"
    }
  },
  "event_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
  "type": "issue.reported"
}

Bidang	Tipe	Deskripsi
`issue_report.severity`	string	`critical`, `warning`, atau `info`
`issue_report.status`	string	`open` atau `resolved`
`issue_report.source`	string	`user` (diajukan dari dasbor) atau `system` (dibuat oleh penilaian)

Menilai ulang sebuah panggilan membangun kembali laporan masalah yang dibuat sistemnya, sehingga mengirim ulang issue.reported untuk laporan yang dibuat kembali. Lakukan deduplikasi berdasarkan call_id + title jika Anda hanya menginginkan satu notifikasi per masalah yang mendasarinya.

Event panggilan uji

`test-call.completed`

Dikirim saat sebuah proses panggilan uji mencapai status terminal — completed atau failed, termasuk proses yang gagal saat peluncuran dan tidak pernah menghasilkan panggilan. Tidak memblokir. Berguna untuk menghubungkan proses CI batch ke sistem chat/notifikasi Anda.

{
  "data": {
    "test_call_run": {
      "call_id": 987654321,
      "completed_at": "2026-04-20T18:25:04.822Z",
      "error_message": "",
      "id": 7110,
      "status": "completed",
      "target_id": 12,
      "target_type": "agent"
    }
  },
  "event_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
  "type": "test-call.completed"
}

Bidang	Tipe	Deskripsi
`test_call_run.target_type`	string	`agent` atau `phone_number`
`test_call_run.target_id`	integer	ID agen atau ID nomor telepon yang menjadi target proses, sesuai dengan `target_type`
`test_call_run.status`	string	`completed` atau `failed`
`test_call_run.call_id`	integer \| null	`null` saat proses gagal sebelum panggilan dilakukan
`test_call_run.error_message`	string	Kosong saat berhasil

Peristiwa alert

`alert.triggered`

Dikirim saat aturan alert dengan channel Kirim ke webhook developer yang diaktifkan melampaui ambangnya. Tidak memblokir. Aturan dipicu sekali lalu mematuhi cooldown-nya, sehingga pelanggaran berkelanjutan menghasilkan satu peristiwa per jendela cooldown.

{
  "data": {
    "comparator": "lt",
    "event_id": "b8e6a1d4-2c3f-4a5b-9c8d-7e6f5a4b3c2d",
    "fired_at": "2026-04-20T18:00:00+00:00",
    "metric": "success_rate",
    "metric_value": 71.4,
    "rule_id": "d2c3b4a5-6f7e-4d8c-9b0a-1c2d3e4f5a6b",
    "rule_name": "Success rate below 80%",
    "threshold": 80.0,
    "window_hours": 24
  },
  "event_id": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a",
  "type": "alert.triggered"
}

Kolom	Tipe	Deskripsi
`event_id` (dalam `data`)	UUID	ID pemicu alert — berbeda dari `event_id` pengiriman pada envelope
`rule_id`, `rule_name`	UUID, string	Aturan yang dipicu
`metric`	string	`success_rate`, `failure_rate`, `avg_score`, `call_volume`, atau `suite_regression`
`comparator`	string	`lt`, `lte`, `gt`, atau `gte`
`metric_value`	number	Nilai metrik selama jendela saat aturan dipicu
`threshold`	number	Ambang yang dikonfigurasi
`window_hours`	integer	Jendela evaluasi berjalan
`fired_at`	timestamp

Lihat panduan Alerts untuk membuat aturan, metrik, cooldown, serta channel email / Slack.

Terkait

telephony.incoming / web.incoming

Payload panggilan masuk yang memblokir dan harus Anda respons.

telephony.complete / web.complete

Transkrip dan metrik setelah panggilan.

Endpoint webhook

Langganan URL ke sebagian peristiwa ini.

Function Tools

Cara peristiwa telephony.tool / web.tool dibuat.

​Event panggilan

​telephony.incoming

​telephony.complete

​telephony.tool

​web.incoming

​web.complete

​web.tool

​Event kualitas

​call.graded

​issue.reported

​Event panggilan uji

​test-call.completed

​Peristiwa alert

​alert.triggered

​Terkait

telephony.incoming / web.incoming

telephony.complete / web.complete

Endpoint webhook

Function Tools

Event panggilan

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

Event kualitas

`call.graded`

`issue.reported`

Event panggilan uji

`test-call.completed`

Peristiwa alert

`alert.triggered`

Terkait