Webhooks

Olay Kataloğu

ThunderPhone

Her webhook gövdesinde, değeri bu sayfadaki olay türlerinden biri olan bir type alanı bulunur. Bir uç noktaya abone olduğunuzda, events dizisi istediğiniz olay türlerini içermelidir (veya her şeye abone olmak için boş bırakılmalıdır — yalnızca açıkça adlandıran uç noktalara iletilen tur başına olaylar telephony.turn / web.turn hariç).

Bu olaylar iki teslimat biçimiyle taşınır:

• Uç nokta teslimatları, yeniden denemelerle birlikte her zaman engellemeyen bildirimlerdir: herhangi bir 2xx ile yanıt verin; zarf, tekilleştirme için bir event_id içerir.
• Engelleyici alışverişler yalnızca eski tek URL'li webhook üzerinde çalışır: telephony.incoming / web.incoming yapılandırma isteği (webhook modundaki numaralar ve widget anahtarları, 10 sn zaman aşımı) ve webhook modundaki araç dağıtımı. Yanıtınız canlı görüşmeyi şekillendirir.

Aşağıdaki örnek yükler, iletim sırasındaki uç nokta zarfını gösterir (anahtarlar alfabetik olarak sıralanmıştır: data, event_id, type); eski teslimatlar, event_id olmadan aynı data verisini taşır.

Çağrı etkinlikleri#

telephony.incoming#

Gelen bir çağrı, telefon numaralarınızdan birine ulaştığında gönderilir. Uç nokta teslimleri, numaranın yapay zeka ajanı için mi yoksa webhook için mi yapılandırıldığından bağımsız olarak her gelen çağrı için gönderilen tetikle-ve-unut bildirimleridir. Atanmış bir yapay zeka ajanı olmayan numaralar, ayrıca eski webhook üzerinde engelleyici yapılandırma isteğini alır — tam istek / yanıt şeması için telephony.incoming / web.incoming bölümüne bakın.

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

telephony.complete#

Gelen veya giden bir telefon çağrısı sona erdiğinde gönderilir. Engelleyici değildir. Konuşma metnini, mevcutsa kayıt URL'sini ve faturalandırma özetini içerir. Yük şeması için telephony.complete / web.complete bölümüne bakın.

telephony.tool#

Bir telefon çağrısı bir fonksiyon aracı çağırdıktan sonra gönderilir. Engelleyici olmayan denetim bildirimi — bu etkinlik teslim edildiğinde araç zaten çalıştırılmıştır; kendi fonksiyon araçlarınızı kapsar (yerleşik, bilgi tabanı, uygulama bağlantısı veya MCP araçlarını değil).

{
  "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, çalıştırılan sonuçtur: başarı durumunda {"status": <http status>, "response": <your endpoint's JSON>}, başarısızlık durumunda ise {"status": <status>, "error": "<message>"}.

telephony.turn#

Bir telefon çağrısı devam ederken, konuşma içeren her tur gerçekleştiğinde bir kez gönderilir — ajanın sesli tamamlamaları ve arayanın yazıya dökülmüş turları. GET /v1/calls/{call_id}/transcript için yoklama yapmak yerine, canlı konuşmayı düz webhook'lar üzerinden takip etmenizi sağlar. Engelleyici değildir.

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

web.incoming#

Bir web bileşeni oturumu veya oluşturucu mikrofon test çağrısı başladığında gönderilen telephony.incoming etkinliğinin web kanalı eşdeğeridir. Uç nokta teslimleri, her web oturumu için tetikle-ve-unut şeklindedir. mode="webhook" içindeki yayımlanabilir anahtarlar ayrıca eski webhook üzerinde engelleyici yapılandırma isteğini alır — bu engelleyici isteğin biçimi farklıdır (origin_domain, publishable_key_prefix; telefon numarası yoktur). telephony.incoming / web.incoming bölümüne bakın.

{
  "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 her zaman değişmez "web" değeridir. Webhook modundaki bileşen oturumlarında to_number boştur (oturumun ajan numarası yapılandırmadan sonra atanır); oluşturucu mikrofon test çağrılarında ise origin_domain ve publishable_key_prefix boştur.

web.complete#

Web bileşeni çağrılarını (direction: "web") ve oluşturucu mikrofon test çağrılarını (direction: "test") kapsayan telephony.complete etkinliğinin web kanalı eşdeğeridir. Engelleyici değildir. telephony.complete ile aynı yük biçimine sahiptir ve ek olarak origin_domain içerir; from_number değeri "web" olarak ayarlanır.

web.tool#

telephony.tool etkinliğinin web kanalı eşdeğeridir. data, from_number / to_number yerine origin_domain taşır.

web.turn#

Web bileşeni çağrılarını ve oluşturucu mikrofon test çağrılarını kapsayan telephony.turn etkinliğinin web kanalı eşdeğeridir. Aynı yük biçimine sahiptir; from_number / to_number yerine origin_domain kullanır. telephony.turn gibi, açık abonelik gerektirir — boş bir events dizisi üzerinden hiçbir zaman teslim edilmez.

Ses olayları#

Özel ses oluşturma eşzamansızdır. Bu engellemeyen olaylar, yoklama yapmak yerine nihai bir sonuca tepki vermenizi sağlar. Klon ayrıntıları uç noktası.

voice.ready#

Özel sesin işlenmesi tamamlanıp bir ajana atanabildiğinde gönderilir.

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

Özel ses işleme süreci kalıcı bir hatayla sonuçlandığında gönderilir.

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

Kalite olayları#

call.graded#

Bir arama için yapay zeka değerlendirme çalıştırması tamamlandığında gönderilir. Engellemez.

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

issue.reported#

Bir sorun raporu oluşturulduğunda gönderilir — rapor ya bir kullanıcı tarafından kontrol panelinden (source: "user") bildirilir ya da arama değerlendirmesi tarafından otomatik olarak (source: "system") oluşturulur. Engellemez.

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

Test araması olayları#

test-call.completed#

Bir test araması çalıştırması son duruma ulaştığında gönderilir — arama başlatma sırasında başarısız olan ve hiç arama oluşturmayan çalıştırmalar dahil olmak üzere completed veya failed. Engellemez. Toplu CI çalıştırmalarını sohbet/bildirim sistemlerinize bağlamak için kullanışlıdır.

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

Uyarı etkinlikleri#

alert.triggered#

Geliştirici web kancalarına teslim et kanalı etkin olan bir uyarı kuralı eşiğini aştığında gönderilir. Engellemez. Bir kural bir kez tetiklenir ve ardından bekleme süresine uyar; bu nedenle devam eden bir ihlal, her bekleme süresi penceresi için bir etkinlik üretir.

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

Kurallar, metrikler, bekleme süreleri ve e-posta / Slack kanalları oluşturmak için Uyarılar kılavuzuna bakın.

İlgili#