Etkinlik Kataloğu

ThunderPhone

Her webhook gövdesi, değeri bu sayfadaki olay türlerinden biri olan bir type alanı içerir. 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 teslim edilen tur başına olaylar telephony.turn / web.turn hariç).

Bu olaylar iki teslimat biçimiyle iletilir:

• Uç nokta teslimatları, yeniden denemeler içeren, 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: bir yeniden deneme dahil 13 sn; webhook modundaki widget anahtarları: 10 sn) ve webhook modundaki araç yönlendirmesi. Yanıtınız canlı çağrıyı şekillendirir.

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

Arama etkinlikleri#

telephony.incoming#

Gelen bir arama telefon numaralarınızdan birine ulaştığında gönderilir. Uç nokta teslimatları, numaranın ajana mı yoksa webhook'a mı yapılandırıldığına bakılmaksızın her gelen arama için gönderilen, beklemeden devam eden bildirimlerdir. Atanmış bir 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 telefon araması sona erdiğinde gönderilir. Engelleyici değildir. Müsait olduğunda transkripti, 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 araması bir fonksiyon aracı çağırdıktan sonra gönderilir. Engelleyici olmayan bir denetim bildirimi niteliğindedir — bu etkinlik teslim edildiğinde araç zaten çalıştırılmıştır; kendi fonksiyon araçlarınızı ve yerleşik send_sms aracını kapsar (diğer yerleşik, bilgi tabanı, uygulama bağlantısı veya MCP araçlarını kapsamaz). send_sms için hem arguments.to hem de arguments.body [REDACTED] olur. Tamamlanma transkriptleri de bunları gizler; içeriği ve alıcıyı, yanıttaki message_id değerini kullanarak kuruluş kapsamlı SMS kaynağından alın.

{
  "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 araması devam ederken, konuşma içeren her dönüş gerçekleştiğinde bir kez gönderilir — ajanın sesli tamamlamaları ve arayanın yazıya dökülen dönüşleri. GET /v1/calls/{call_id}/transcript sorgulaması 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 araması başladığında gönderilen, telephony.incoming etkinliğinin web kanalı eşdeğeridir. Uç nokta teslimatları, her web oturumu için beklemeden devam eder. mode="webhook" içindeki yayınlanabilir anahtarlar ayrıca eski webhook üzerinde engelleyici yapılandırma isteğini alır — bu engelleyici istek farklı bir biçime sahiptir (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 aramalarında ise origin_domain ve publishable_key_prefix boştur.

web.complete#

Web bileşeni aramalarını (direction: "web") ve oluşturucu mikrofon test aramaları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; ayrıca origin_domain içerir ve 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 aramalarını ve oluşturucu mikrofon test aramalarını kapsayan telephony.turn etkinliğinin web kanalı eşdeğeridir. Aynı yük biçimine sahiptir, ancak from_number / to_number yerine origin_domain kullanır. telephony.turn gibi, açık abonelik gerektirir — boş bir events dizisi üzerinden asla teslim edilmez.

call.transfer_completed#

Bir çağrı aktarımının nihai sonucuyla, çağrı başına bir kez gönderilir: soğuk aktarım veya sesli AI ajanı ayrıldıktan sonra sıcak aktarımın geride bıraktığı insanlar arası köprü. Engelleyici değildir ve yalnızca uç noktalara teslim edilir (eski tek URL'li webhook'a asla gönderilmez). Çağrının telephony.complete olayından sonra ulaşır: operatör çağrıyı devraldığında veya aktarım başarısız olduğunda ya da ThunderPhone çağrıyı köprülediyse köprü sona erdiğinde.

{
  "data": {
    "agent_id": 12,
    "agent_name": "Front desk",
    "bridge_kind": "cold_fallback",
    "bridge_seconds": 255,
    "bridge_total_cents": 5,
    "call_id": 987654321,
    "destination": "+15555550102",
    "sip_status": 403,
    "transfer_outcome": "bridged"
  },
  "event_id": "5b0f6c1e-9d2a-5e7b-8c4d-1a2b3c4d5e6f",
  "type": "call.transfer_completed"
}

Aynı değerler, çağrı nesnesinde transfer_outcome, transfer_destination, transfer_sip_status, transfer_bridge_kind, transfer_bridge_seconds ve transfer_bridge_total_cents olarak da bulunur. event_id, bir çağrı için her teslimatta aynıdır; bu nedenle yinelenen bir rapor ikinci bir etkinlik oluşturmaz.

SMS olayları#

SMS olayları, kuruluşun bağlı Twilio veya Telnyx hesabı üzerinden gönderilen mesajları açıklar. Mesaj gövdesi dahil edilmez ve to gizlenir. İçerik veya alıcı gerektiğinde kuruluş kapsamındaki mesajı GET /v1/sms/{message_id} ile alın.

sms.sent#

Müşterinin operatörü giden SMS isteğini kabul ettiğinde gönderilir. Bu, cihaz teslim alındısı değildir.

{
  "data": {
    "accepted_at": "2026-09-19T15:42:10.113Z",
    "agent_id": 12,
    "call_id": 987654321,
    "created_at": "2026-09-19T15:42:09.901Z",
    "direction": "outbound",
    "error_code": null,
    "error_message": null,
    "from_number": "+15551234567",
    "id": "313a3117-827b-46e9-a01a-ac1493838724",
    "provider": "twilio",
    "provider_id": "SM0123456789abcdef0123456789abcdef",
    "segment_count": 1,
    "source": "agent_tool",
    "status": "accepted",
    "to": "[REDACTED]"
  },
  "event_id": "0ae347b4-1716-45bb-9a0e-b52373586e37",
  "type": "sms.sent"
}

sms.failed#

Kalıcı bir operatör reddinden sonra, geçici hatalar için yeniden deneme hakları tükendiğinde veya sonuç kesin olarak bilinmediğinde gönderilir. error_code sabit bir ThunderPhone kodudur ve error_message, mevcut olduğunda müşterinin yapması gereken işlemi belirtir. status: "unknown", operatörün SMS'i kabul etmiş olabileceği anlamına gelir; ThunderPhone bunu otomatik olarak yeniden göndermeyeceğinden, operatör günlüğünde mutabakat sağlayın.

sms.received#

Gelen SMS desteği için ayrılmıştır. Mevcut sürümde hiçbir sms.received olayı yayınlanmaz. Gelen operatör webhook yapılandırması ve imza doğrulaması ayrı olarak sunulacaktır.

Ses olayları#

Özel ses oluşturma işlemi eşzamansızdır. Bu engellemeyen olaylar, klon ayrıntı uç noktasını yoklamak yerine kesin bir sonuca tepki vermenizi sağlar.

voice.ready ve voice.failed yalnızca events: [] içeren kuruluş genelindeki bir uç noktaya teslim edilir. Açık olay filtreleri olarak seçilemezler.

voice.ready#

Özel ses işlenmeyi tamamladığında ve 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 kalıcı bir hataya ulaştığı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 çağrı için AI derecelendirme çalışması tamamlandığında gönderilir. Engelleyici değildir.

{
  "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…"
    },
    "report": null
  },
  "event_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "type": "call.graded"
}

call.data_extracted#

Yapılandırılmış veri çıkarma başarıyla tamamlandığında gönderilir; buna telephony.complete / web.complete sonrasındaki geç yeniden deneme veya POST /v1/calls/{call_id}/extract ile manuel yeniden çalıştırma da dahildir. Engelleyici değildir.

Engelleyici çıkarma modunda, tamamlama olayı normalde 75 saniyelik çıkarma bütçesinden daha uzun süre beklemez. Çıkarma çalışanı işlemi kaybolursa, üretim sonlandırma boşaltması (her beş dakikada bir), başka bir çıkarma girişimi başlatmadan önce blocking_deadline_at süresi geçmiş bir tamamlamayı serbest bırakır. Daha sonraki bir başarı, bu olay olarak ayrı şekilde teslim edilir.

{
  "data": {
    "call_id": 987654321,
    "agent_id": 12,
    "agent_name": "Acme intake",
    "extracted_data": {
      "status": "completed",
      "fields": {
        "customer_name": "Alex Morgan",
        "appointment_date": "2026-04-23"
      },
      "evidence": {
        "customer_name": {
          "quote": "My name is Alex Morgan",
          "speaker_role": "caller",
          "turn_index": 4
        },
        "appointment_date": {
          "quote": "April 23 works for me",
          "speaker_role": "caller",
          "turn_index": 7
        }
      },
      "verification": "verified",
      "field_reasons": {},
      "schema_version": "92850758e231a3c95a..."
    },
    "extracted_at": "2026-04-20T18:25:11.002Z",
    "model": "<model id>",
    "summary": "Alex Morgan called to book a follow-up visit and confirmed Thursday, April 23."
  },
  "event_id": "4d79ef1d-c2b1-4ed6-85b8-8326bd2895ef",
  "type": "call.data_extracted"
}

campaign.completed#

Bir kampanya, zamanlaması sona erdiğinde veya tüm kişiler nihai durumlara ulaştığında, running durumundan completed durumuna geçtiğinde bir kez gönderilir. Çalıştırıcı yeniden denemeleri başka bir olay göndermez. Bu kuruluş düzeyindeki yaşam döngüsü olayı yalnızca kuruluş kapsamlı uç noktalara teslim edilir, ajan kapsamlı uç noktalara teslim edilmez. Engelleyici değildir.

{
  "data": {
    "campaign_id": "3f6b2c9e-2a0d-4c63-b6d6-a708dc98f403",
    "name": "May win-back",
    "agent_id": 12,
    "status": "completed",
    "started_at": "2026-04-20T17:00:00Z",
    "completed_at": "2026-04-20T18:25:11Z",
    "counts": {
      "contacts_total": 150,
      "completed": 121,
      "failed": 11,
      "no_answer": 18,
      "remaining": 0
    }
  },
  "event_id": "8d8f52ce-6b46-423f-9dde-cea0b91ec135",
  "type": "campaign.completed"
}

Dört sonuç sayısı birbirinden ayrıdır ve toplamları contacts_total değerine eşittir: completed, başarılı kişileri içerir; no_answer, nihai sonucu yanıt yok olan nihai başarısız/tükenmiş kişileri içerir; failed, diğer tüm nihai başarısız/tükenmiş kişileri içerir; remaining ise bekleyen, zamanlanmış veya şu anda aranan kişileri içerir. Yeniden deneme bekleyen bir kişi, en son girişiminde yanıt alınmamış olsa bile remaining olur. Devam eden çağrılar, yalnızca bir kez alınan tamamlama anlık görüntüsünden önce uzlaştırılır. started_at, yapılandırılmış kampanya başlangıcıdır veya başlangıç yapılandırılmadıysa kampanya oluşturulma zamanıdır.

issue.reported#

Bir sorun raporu oluşturulduğunda gönderilir — rapor ya kullanıcı tarafından kontrol panelinden (source: "user") iletilir ya da çağrı derecelendirmesi tarafından otomatik olarak (source: "system") oluşturulur. Engelleyici değildir.

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

issue.escalated#

Bir sorun örüntüsü personel incelemesi için ThunderPhone'a gönderildiğinde gönderilir: ThunderPhone'a bildir işleminden sonra veya Yapay zeka ile düzeltme, müşteri tarafındaki düzeltmeyi onaylayamadığında ve sorunu otomatik olarak yönlendirdiğinde. Bu olayı yalnızca kuruluş genelindeki uç noktalar alır.

{
  "data": {
    "automatic": false,
    "cluster_id": "7ac2844c-2df0-4fa8-a560-7378da649e19",
    "escalation_id": "ec99f52b-c8c0-41dd-a4f2-dd8a07b10894",
    "status": "open"
  },
  "event_id": "d8f8f420-7a42-45ba-bcf1-b747f9bbecda",
  "type": "issue.escalated"
}

Bu bir bildirimdir, kanıt paketi değildir. Sorun örüntüsüyle ilişkilendirmek için cluster_id kullanın. ThunderPhone'a bildir bölümüne bakın.

Test çağrısı etkinlikleri#

test-call.completed#

Bir test çağrısı çalıştırması çağrı başlatılırken başarısız olan ve hiç çağrı oluşturmayan çalıştırmalar dahil olmak üzere completed veya failed nihai durumuna ulaştığında gönderilir. 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 sürekli bir ihlal, her bekleme süresi penceresinde 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 rehberine bakın.

Geçiş etkinlikleri#

migration.call.complete#

POST /v1/migrations/{id}/calls üzerinden yapılan bir arama, hangi platformun aramayı gerçekleştirdiğine bakılmaksızın sona erdiğinde gönderilir. Engelleyici değildir. Arama sona erdikten yaklaşık 5 dakika sonrasına kadar ulaşabilir. data, telephony.complete içindeki tüm alanlara ek olarak bir migration bloğu içerir. ThunderPhone'un yaptığı bir arama, aynı call_id ile her zamanki gibi telephony.complete de gönderir. Diğer platformdaki bir arama 2 saat sonra hâlâ bitmediyse ya da geçiş tamamlandıysa veya anahtarını önce kaybettiyse, status: "unknown" ve transkript olmadan gönderilir.

{
  "data": {
    "agent_id": 42,
    "agent_name": "Front desk",
    "billable_minutes": null,
    "billing_total_cents": null,
    "call_id": null,
    "direction": "outbound",
    "duration_seconds": 94,
    "end_reason": "user_hangup",
    "end_time": "2026-10-06T17:01:34+00:00",
    "extracted_data": null,
    "from_number": "+15551234567",
    "migration": {
      "arm": "vendor",
      "id": "5f0c2a9e-7b1d-4c3e-8a6f-2d9e1b4c7a30",
      "metadata": {
        "lead_id": "8812"
      },
      "routing_id": "9b2f8c1e-4d3a-4f6b-8e2d-1a7c5b9e0f34",
      "vendor": "retell",
      "vendor_call_id": "call_6a1f0e",
      "vendor_cost_usd": "0.1240"
    },
    "product": "",
    "recording_mode": "vendor",
    "recording_url": "https://…",
    "start_time": "2026-10-06T17:00:00+00:00",
    "status": "completed",
    "summary": "The callee booked a table for two on Thursday.",
    "thunderphone_retained_call_content": true,
    "to_number": "+14155552671",
    "transcripts": [
      {
        "content": "Hi Ada, this is Rosa's calling about your booking.",
        "role": "agent"
      },
      {
        "content": "Yes, Thursday works.",
        "role": "user"
      }
    ],
    "transfer_number": null,
    "unresolved_variables": [],
    "variables": {
      "first_name": "Ada"
    },
    "voice": ""
  },
  "event_id": "7c1e2f3a-4b5c-4d6e-8f7a-9b0c1d2e3f4a",
  "type": "migration.call.complete"
}

Bir vendor araması için ThunderPhone'da faturalandırma veya veri çıkarma bilgisi yoktur: billable_minutes, billing_total_cents ve extracted_data null değerindedir, product ve voice boştur, recording_mode vendor değerindedir ve recording_url, sağlandıysa diğer platformun bağlantısıdır.

migration.rollback#

Bir geçişin kademeli geçişi tüm aramaları kendiliğinden diğer platforma geri taşıdığında gönderilir: 15 dakika içinde 3 arama ThunderPhone'a bağlanamadığında, ThunderPhone'a gönderilen 2 arama yapay zeka ajanı yanıtlamadan önce sonlandığında veya ThunderPhone'un görev sonuç oranı diğer platformunkinin yapılandırılan farktan daha fazla altına düştüğünde. Engellemez; geri alma başına bir kez gönderilir. Ardından ThunderPhone'un payı %0 olur ve geçiş, biri ajanın Geçiş sekmesinden yeniden başlatana kadar duraklatılır. Yük telefon numarası, transkript veya arama kimliği içermez.

{
  "data": {
    "agent_id": 42,
    "agent_name": "Front desk",
    "dropped": 0,
    "migration_id": "5f0c2a9e-7b1d-4c3e-8a6f-2d9e1b4c7a30",
    "ours": {
      "graded": 20,
      "success_rate": 0.8
    },
    "ours_failed": 3,
    "ours_percent": 0,
    "previous_percent": 25,
    "reason": "ours_failed_burst",
    "rolled_back_at": "2026-10-10T12:05:00+00:00",
    "step": 1,
    "theirs": {
      "graded": 20,
      "success_rate": 0.8
    },
    "vendor": "retell"
  },
  "event_id": "3d1f6b2a-8c4e-5a7b-9d0e-2f1a3b4c5d6e",
  "type": "migration.rollback"
}

İlgili#