Katalog Peristiwa

Semua jenis peristiwa webhook yang dipancarkan ThunderPhone.

Setiap body webhook memiliki kolom type yang nilainya adalah salah satu jenis event di halaman ini. Saat Anda berlangganan ke sebuah endpoint, array events harus berisi jenis event yang Anda inginkan (atau kosong untuk berlangganan ke semuanya — kecuali event per-giliran telephony.turn / web.turn, yang hanya dikirimkan ke endpoint yang menyebutkannya secara eksplisit).

Dua gaya pengiriman membawa event 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 distribusi 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.

Peristiwa panggilan

`telephony.incoming`

Dikirim ketika panggilan masuk mencapai salah satu nomor telepon Anda. Pengiriman 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 blocking 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-blocking. Mencakup transkrip, URL rekaman jika tersedia, dan ringkasan penagihan. Lihat telephony.complete / web.complete untuk skema payload.

`telephony.tool`

Dikirim setelah panggilan telepon memanggil function tool. Notifikasi audit non-blocking — tool telah dijalankan saat peristiwa ini dikirim; peristiwa 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.

`telephony.turn`

Dikirim saat panggilan telepon sedang berlangsung, satu kali untuk setiap giliran yang berisi ucapan saat terjadi — penyelesaian lisan agen dan giliran penelepon yang ditranskripsikan. Memungkinkan Anda mengikuti percakapan langsung melalui webhook biasa alih-alih melakukan polling pada GET /v1/calls/{call_id}/transcript. Non-blocking.

{
  "data": {
    "call_id": 987654321,
    "entry_type": "completion",
    "from_number": "+14155550199",
    "position": 7,
    "role": "assistant",
    "start_ms": 15200,
    "text": "How many employees does your company have?",
    "to_number": "+15551234567"
  },
  "event_id": "8d3f5a2c-7b1e-4c9a-b6d0-2e4f6a8c0d1e",
  "type": "telephony.turn"
}

Bidang	Tipe	Deskripsi
`position`	integer	Indeks giliran dalam riwayat panggilan — identitas stabil untuk pengurutan
`role`	string	`assistant` (ucapan agen) atau `user` (ucapan penelepon)
`text`	string	Teks transkrip giliran sebagaimana diketahui pada waktu pengiriman
`entry_type`	string	Jenis entri riwayat yang mendasari: `completion` (agen), atau `user_turn` / `span` (penelepon)
`start_ms`, `end_ms`	integer	Offset audio dalam md sejak panggilan dimulai; hanya ada ketika waktu pemutaran sudah diketahui pada waktu pengiriman

`web.incoming`

Padanan kanal web untuk telephony.incoming, dikirim ketika sesi widget web atau panggilan uji mikrofon builder dimulai. Pengiriman endpoint bersifat fire-and-forget untuk setiap sesi web. Publishable key dalam mode="webhook" juga menerima permintaan konfigurasi blocking pada webhook lama — permintaan blocking 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 mode webhook, to_number kosong (nomor agen sesi ditetapkan setelah konfigurasi); untuk panggilan uji mikrofon builder, origin_domain dan publishable_key_prefix kosong.

`web.complete`

Padanan kanal web untuk telephony.complete, yang mencakup panggilan widget web (direction: "web") dan panggilan uji mikrofon builder (direction: "test"). Non-blocking. Bentuk payload sama seperti telephony.complete, ditambah origin_domain, dengan from_number ditetapkan ke "web".

`web.tool`

Padanan kanal web untuk telephony.tool. data memuat origin_domain, bukan from_number / to_number.

`web.turn`

Padanan kanal web untuk telephony.turn, yang mencakup panggilan widget web dan panggilan uji mikrofon builder. Bentuk payload sama, dengan origin_domain menggantikan from_number / to_number. Seperti telephony.turn, peristiwa ini memerlukan langganan eksplisit — peristiwa ini tidak pernah dikirim melalui array events kosong.

Peristiwa suara

Pembuatan suara kustom bersifat asinkron. Peristiwa non-pemblokiran ini memungkinkan Anda merespons hasil akhir alih-alih melakukan polling pada endpoint detail kloning.

`voice.ready`

Dikirim saat suara kustom selesai diproses dan dapat ditetapkan ke agen.

{
  "data": {
    "voice": {
      "created_at": "2026-07-30T14:12:08.317Z",
      "display_name": "Support voice",
      "failure_reason": "",
      "gender": "female",
      "id": "cv_2f6f90b0e9a34ee8b39be7d1",
      "language": "en",
      "name": "custom:cv_2f6f90b0e9a34ee8b39be7d1",
      "status": "ready",
      "updated_at": "2026-07-30T14:13:31.605Z"
    }
  },
  "event_id": "2d5f0a61-e9b5-4a3c-b684-29d7d9e4b214",
  "type": "voice.ready"
}

`voice.failed`

Dikirim saat pemrosesan suara kustom mengalami kegagalan permanen.

{
  "data": {
    "reason": "audio sample could not be processed",
    "voice": {
      "created_at": "2026-07-30T14:12:08.317Z",
      "display_name": "Support voice",
      "failure_reason": "audio sample could not be processed",
      "gender": "female",
      "id": "cv_2f6f90b0e9a34ee8b39be7d1",
      "language": "en",
      "name": "custom:cv_2f6f90b0e9a34ee8b39be7d1",
      "status": "failed",
      "updated_at": "2026-07-30T14:13:31.605Z"
    }
  },
  "event_id": "3493e985-1a75-4f77-a10a-e74af440cd31",
  "type": "voice.failed"
}

Kolom	Tipe	Deskripsi
`voice.id`	string	ID publik suara kustom
`voice.name`	string	Nilai suara agen dalam format `custom:<public_id>`
`voice.display_name`	string	Nama suara yang ditampilkan kepada organisasi
`voice.language`	string	Kode bahasa tunggal kloning
`voice.gender`	string	`male`, `female`, atau string kosong
`voice.status`	string	`ready` untuk `voice.ready`; `failed` untuk `voice.failed`
`voice.failure_reason`	string	Kosong saat berhasil; detail kegagalan pemrosesan saat gagal
`voice.created_at`, `voice.updated_at`	timestamp	Stempel waktu ISO 8601
`reason`	string	Detail kegagalan; hanya ada pada `voice.failed`

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

Kolom	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 mengirimkan peristiwa
`grade.grader_model`	string	Penilai yang menghasilkan hasil (misalnya `heuristic-v1`)
`grade.graded_at`, `grade.created_at`	timestamp

`issue.reported`

Dikirim ketika sebuah 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"
}

Kolom	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)

Peristiwa panggilan uji

`test-call.completed`

Dikirim ketika 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"
}

Kolom	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` ketika proses gagal sebelum panggilan dilakukan
`test_call_run.error_message`	string	Kosong jika berhasil

Peristiwa peringatan

`alert.triggered`

Dikirim saat sebuah aturan peringatan dengan kanal Kirim ke webhook developer yang diaktifkan melampaui ambangnya. Tidak memblokir. Aturan dipicu sekali lalu mematuhi periode 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"
}

Bidang	Tipe	Deskripsi
`event_id` (dalam `data`)	UUID	ID pemicu peringatan — 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 Peringatan untuk membuat aturan, metrik, cooldown, serta kanal 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

Langganankan URL ke sebagian peristiwa ini.

Function Tools

Cara peristiwa telephony.tool / web.tool dibuat.