Open in
事件目錄
ThunderPhone 發出的所有 webhook 事件類型。
每個 webhook 主體都有一個 type 欄位,其值為本頁其中一種事件
類型。當你訂閱某個
端點 時,events 陣列必須包含你需要的
事件類型(或留空以訂閱所有事件——惟每輪事件 telephony.turn /
web.turn 及即時進度事件
call.status_changed 除外;這些事件只會傳送至明確列出它們的
端點)。
這些事件提供兩種傳送方式:
- 端點傳送一律屬於非阻塞通知,並設有重試機制:以任何 2xx 回應即可;封裝載有
event_id,可用於去重。 - 阻塞交換只會在舊版單一 URL webhook上執行:包括
telephony.incoming/web.incoming設定請求(webhook 模式號碼:13 秒,包括一次重試;webhook 模式小工具金鑰:10 秒),以及 webhook 模式的工具派送。你的回應會影響即時通話。
以下的範例有效載荷會以傳輸順序顯示端點封包
(鍵會按英文字母排序:data、event_id、type);舊版傳送包含相同的 data,但不含 event_id。
通話事件
telephony.incoming
當來電到達你的其中一個
電話號碼時發送。端點傳送屬於即發即棄通知,會針對每一個來電發送,不論該號碼是否已設定智能體或 webhook。未指派智能體的號碼,亦會透過舊版 webhook 收到阻塞式設定請求——完整的請求/回應 schema,請參閱
telephony.incoming / web.incoming。
{
"data": {
"call_id": 987654321,
"from_number": "+14155550199",
"to_number": "+15551234567"
},
"event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11",
"type": "telephony.incoming"
}| 欄位 | 類型 | 說明 |
|---|---|---|
agent_id | integer | null | 已指派時,處理此通話的智能體 |
agent_name | string | null | 已指派時,處理此通話的智能體 |
returning_call | object | 僅當此號碼在過去 30 日內曾致電此來電者時提供:較早前通話的 call_id、agent_id、started_at 及 outcome。參閱 回撥 |
sip_headers | object | 僅當通話附帶 X-* 或 User-to-User SIP 標頭時提供(SIP 位址及手動 SIP 連線):以小寫表示的標頭名稱 → 值。參閱 SIP 標頭 |
telephony.complete
當來電或撥出電話結束時發送。非阻塞式。
包括逐字稿、錄音 URL(如適用)及收費摘要。Payload schema 請參閱
telephony.complete / web.complete。
| 欄位 | 類型 | 說明 |
|---|---|---|
agent_id | integer | null | 處理通話的智能體(如已指派) |
agent_name | string | null | 處理通話的智能體名稱(如已指派) |
telephony.tool
當電話通話呼叫
函數工具後發送。此為非阻塞式稽核通知——傳送此事件時,工具已經執行;涵蓋你自訂的函數工具及內置 send_sms 工具(不包括其他內置工具、知識庫、應用程式連接或 MCP 工具)。對於 send_sms,
arguments.to 及 arguments.body 均為 [REDACTED]。完成逐字稿亦會遮蔽這些內容;請使用回應中的 message_id,從組織範圍的 SMS 資源擷取內容及收件人。
{
"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 為已執行的結果:成功時為 {"status": <http status>, "response": <your endpoint's JSON>},失敗時為
{"status": <status>, "error": "<message>"}。
| 欄位 | 類型 | 說明 |
|---|---|---|
agent_id | integer | null | 處理通話的智能體(如已指派) |
agent_name | string | null | 處理通話的智能體名稱(如已指派) |
telephony.turn
在電話通話進行期間發送,每個包含語音的回合均會於發生時發送一次——包括智能體的語音完成內容,以及來電者的轉錄回合。你可透過一般 webhook 追蹤即時對話,無需輪詢
GET /v1/calls/{call_id}/transcript。
非阻塞式。
{
"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"
}| 欄位 | 類型 | 說明 |
|---|---|---|
agent_id | integer | null | 處理通話的智能體(如已指派) |
agent_name | string | null | 處理通話的智能體名稱(如已指派) |
position | integer | 回合在通話記錄中的索引——用於排序的穩定識別碼 |
role | string | assistant(智能體語音)或 user(來電者語音) |
text | string | 發送當刻所知的回合逐字稿文字 |
entry_type | string | 底層記錄項目類型:completion(智能體)或 user_turn / span(來電者) |
start_ms, end_ms | integer | 自通話開始起計的音訊偏移量(毫秒);僅在發送當刻已知播放時間時提供 |
web.incoming
telephony.incoming 的網頁渠道對應事件,當
網頁小工具工作階段或建構器咪高峰測試通話開始時發送。端點傳送會針對每個網頁工作階段即發即棄。處於 mode="webhook" 的可發佈金鑰,亦會透過舊版 webhook 收到阻塞式設定請求——該阻塞式請求採用不同格式(origin_domain、
publishable_key_prefix;不含電話號碼)。請參閱
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 一律為字面值 "web"。對於 webhook 模式的小工具工作階段,
to_number 為空白(工作階段的智能體號碼會在設定後指派);對於建構器咪高峰測試通話,origin_domain 及
publishable_key_prefix 為空白。
| 欄位 | 類型 | 說明 |
|---|---|---|
agent_id | integer | null | 處理通話的智能體(如已指派) |
agent_name | string | null | 處理通話的智能體名稱(如已指派) |
web.complete
telephony.complete 的網頁渠道對應事件,涵蓋網頁小工具通話(direction: "web")及建構器咪高峰測試通話
(direction: "test")。非阻塞式。Payload 格式與
telephony.complete 相同,另加 origin_domain,
而 from_number 設為 "web"。
| 欄位 | 類型 | 說明 |
|---|---|---|
agent_id | integer | null | 處理通話的智能體(如已指派) |
agent_name | string | null | 處理通話的智能體名稱(如已指派) |
web.tool
telephony.tool 的網頁渠道對應事件。data 使用
origin_domain,而非 from_number / to_number。
| 欄位 | 類型 | 說明 |
|---|---|---|
agent_id | integer | null | 處理通話的智能體(如已指派) |
agent_name | string | null | 處理通話的智能體名稱(如已指派) |
web.turn
telephony.turn 的網頁渠道對應事件,涵蓋網頁小工具通話及建構器咪高峰測試通話。Payload 格式相同,但以 origin_domain 取代 from_number / to_number。與 telephony.turn 相同,此事件需要明確訂閱——絕不會透過空白 events 陣列傳送。
| 欄位 | 類型 | 說明 |
|---|---|---|
agent_id | integer | null | 處理通話的智能體(如已指派) |
agent_name | string | null | 處理通話的智能體名稱(如已指派) |
call.transfer_completed
每次通話會傳送一次,包含最終結果:
通話轉接的冷轉接,或暖轉接中智能體退出後留下的真人通話橋接。
此事件為非阻塞,且只會傳送至端點(絕不傳送至舊式的
單一 URL webhook)。事件會在通話的 telephony.complete 之後到達:
當電訊商接手通話或轉接失敗後;如 ThunderPhone
橋接通話,則會在橋接結束後到達。
{
"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"
}| 欄位 | 類型 | 說明 |
|---|---|---|
call_id | integer | 已轉接的通話 |
agent_id | integer | null | 已指派時,處理該通話的智能體 |
agent_name | string | null | 已指派時,處理該通話的智能體 |
transfer_outcome | string | refer_accepted:電訊商已接手通話。bridged:ThunderPhone 自行維持來電者與目的地之間的連線,原因可能是電訊商拒絕冷轉接,或暖轉接的智能體已退出。bridge_unanswered:電訊商拒絕冷轉接,而目的地未有接聽 ThunderPhone 自行撥出的通話。failed:轉接未能完成,通話已結束 |
destination | string | null | 通話轉接至的號碼 |
sip_status | integer | null | 電訊商拒絕冷轉接時的 SIP 狀態:403(例如不支援通話轉接的 Twilio trunk)、405 或 501。如電訊商沒有拒絕,則為 null |
bridge_kind | string | null | 僅適用於 bridged:cold_fallback(ThunderPhone 連接的被拒冷轉接)或 warm(智能體退出後暖轉接中的兩位真人) |
bridge_seconds | integer | null | 僅適用於 bridged:ThunderPhone 計費的橋接時間,以秒為單位 |
bridge_total_cents | integer | null | 僅適用於 bridged:扣除任何免費通話額度後,橋接的美元美分費用;此費用與通話的 billing_total_cents 分開計費 |
相同數值亦會顯示於通話物件
中的 transfer_outcome、transfer_destination、transfer_sip_status、
transfer_bridge_kind、transfer_bridge_seconds 及
transfer_bridge_total_cents。同一通話的每次傳送均使用相同的 event_id,
因此重複報告不會產生第二個事件。
call.billed
用量計費通話會發送此事件:費用結算時、通話結束後幾分鐘(用量資料到達後),以及其後到達的用量提高費用時。通話的
telephony.complete / web.complete 事件會包含 billing_pending: true 及 null 計費欄位。此事件不會阻塞流程,且只會傳送至端點(絕不會傳送至舊版單一 URL webhook)。在通話結束時已計費的通話,會在完成事件中包含計費資料,且不會收到 call.billed。
事件順序不保證:費用通常會等待完成事件,但 call.billed 可以先到達(例如完成事件延遲一小時,或於不同時間重試傳送),而兩個 call.billed 事件亦可能亂序到達。請為每個 call_id 保留 billing_seq 最高的事件。
{
"data": {
"adjustment_cents": null,
"agent_id": 12,
"agent_name": "Front desk",
"billable_minutes": 3.0,
"billing_seq": 1,
"billing_total_cents": 10,
"call_id": 987654321,
"reason": "settled"
},
"event_id": "7c1d2e3f-4a5b-5c6d-8e7f-9a0b1c2d3e4f",
"type": "call.billed"
}| 欄位 | 類型 | 說明 |
|---|---|---|
call_id | integer | 已計費的通話 |
agent_id | integer | null | 已指派智能體時,處理該通話的智能體 |
agent_name | string | null | 已指派智能體時,處理該通話的智能體 |
reason | string | settled:通話費用。adjusted:費用結算後到達並提高費用的用量(費用絕不會下調) |
billing_seq | integer | 費用為 1,其後每次增加依序為 2、3、...。收到的最高值即為通話目前的計費資料 |
billable_minutes | number | 計費分鐘數,四捨五入至最接近的四分一分鐘 |
billing_total_cents | integer | 通話至今已收取的所有美元美仙費用,扣除任何免費通話額度後計算,包括 adjusted 增加額 |
adjustment_cents | integer | null | 僅適用於 adjusted:此次增加的美元美仙金額,扣除任何免費通話額度後計算 |
相同總額亦會顯示於通話物件中的 billable_minutes 及 billing_total_cents。每次傳送同一個 billing_seq 時,event_id 都相同,因此重複報告不會產生第二個事件。
call.status_changed
通話處於進行中時,每次進入新階段便會發送: ThunderPhone 開始撥號、對方或其電話接聽、智能體接通留言信箱,或智能體被保留及解除保留。你可在跟隨通話的聊天討論串中顯示即時通話進度,例如「正在撥號…」、「已接聽」、「保留中」及「保留 4 分鐘後已解除」。 此事件不會阻塞流程,且只會傳送至端點(絕不傳送至舊有的單一 URL Webhook)。
{
"data": {
"agent_id": 12,
"agent_name": "Front desk",
"call_id": 987654321,
"direction": "outbound",
"hold_seconds": 240,
"occurred_at": "2026-11-07T17:04:12.418Z",
"status": "off_hold"
},
"event_id": "2f6a1c9e-3b7d-5e8f-9a0b-4c5d6e7f8a9b",
"type": "call.status_changed"
}| 欄位 | 類型 | 說明 |
|---|---|---|
call_id | integer | 通話 |
agent_id | integer | null | 已指派時,處理通話的智能體 |
agent_name | string | null | 已指派時,處理通話的智能體 |
direction | string | 通話方向,與通話物件中的定義一致 |
status | string | 通話到達的階段;請參閱下表 |
occurred_at | timestamp | 發生時間 |
hold_seconds | integer | null | 僅適用於 off_hold:保留持續時間,以秒為單位。其他所有狀態均為 null |
status | 發送時機 |
|---|---|
dialing | 外撥通話:ThunderPhone 正在撥出電話。在撥號要求交予電訊商前、所有可能拒絕通話的檢查完成後發送一次。從控制台發起的測試通話不會發送此事件 |
answered | 外撥通話:電訊商回報通話已接聽。留言信箱或來電過濾服務接聽亦計算在內,因此其後可發送 voicemail。如 ThunderPhone 只從通話結束報告得知通話已接聽,則會在通話結束時發送 answered |
voicemail | 外撥通話:智能體已接通留言信箱,並正按智能體的 voicemail_action 留言或掛線。在確認留言信箱後發送(聽到提示音或無人回應),而非基於首次推測 |
on_hold | 智能體被保留並靜默等候(使用 wait_on_hold 工具) |
off_hold | 有人重新接聽,智能體再次交談。hold_seconds 表示保留持續時間 |
每通通話每個狀態最多發送一次,on_hold 及 off_hold 除外,
兩者會在每次保留時各發送一次。一次典型的外撥通話如曾保留等候,
會依次發送 dialing、answered、on_hold、off_hold,並在結束時發送
telephony.complete。
系統不會回報響鈴狀態:各電訊商是否發出響鈴訊號差異太大,無法作為可靠依據。在少數採用 voicemail_action: "prompt" 的通話中,由智能體的提示而非 ThunderPhone 決定如何處理留言信箱,因此不會發送 voicemail 狀態;telephony.complete 中的 answered_by 仍會顯示 voicemail。Payload 不包含逐字稿、電話號碼或變數,因此即使通話錄音已關閉,仍會發送 call.status_changed。
SMS 事件
SMS 事件描述透過機構已連接的
Twilio 或 Telnyx 帳戶發送的訊息。訊息內容會省略,而 to 會被遮蔽。
如需訊息內容或收件人,請從
GET /v1/sms/{message_id} 擷取機構範圍內的訊息。source 可以是 api、agent_tool、followup
或 pre_call(活動在致電前發送的短訊),詳見
訊息物件。
每個 SMS 事件均包含 scheduled_send_id:即該短訊所屬的
預定發送 ID;如短訊並非預定發送,則為
null。預定短訊的 source 為
"scheduled"。
sms.sent
當客戶的電訊商接受外發 SMS 請求時發送。這並非手機送達回條。
{
"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",
"scheduled_send_id": null,
"segment_count": 1,
"source": "agent_tool",
"status": "accepted",
"to": "[REDACTED]"
},
"event_id": "0ae347b4-1716-45bb-9a0e-b52373586e37",
"type": "sms.sent"
}sms.failed
在電訊商永久拒絕後、暫時性重試耗盡後、結果最終無法確定時,或 Twilio 回報已接受的訊息未能送達或失敗時發送。在最後一種情況下,該訊息的
sms.sent 已經發送,而 status 會維持為 "accepted"。error_code 是穩定的
ThunderPhone 代碼,而 error_message 會在可提供時說明客戶應採取的行動。status: "unknown" 表示電訊商可能已接受該 SMS;
請在電訊商記錄中核對,因為 ThunderPhone 不會自動重新發送。
sms.received
保留供收件 SMS 支援使用。現時版本不會發出 sms.received 事件。收件電訊商 webhook 設定及簽名驗證將會另行推出。
已排定事件
未能發出的已排定發送會觸發以下其中一個事件。成功發出的排定發送則會觸發一般事件:短訊會觸發已設定 scheduled_send_id 的 sms.* 事件;通話會觸發通話事件,並在其 telephony.complete 中包含 scheduled_send_id。兩者均為非阻塞式。若發送已指派智能體,該智能體範圍內的端點亦會接收這些事件。
Payload 僅包含 ID、狀態及時間:絕不包含短訊內容、通話變數或內容,且 to 會被遮蔽。其餘資料請取得
GET /v1/scheduled/{id}。
scheduled.skipped
當系統有意不發送時觸發。reason 可為 expired(未能在 expires_at 前發出)、opted_out(該號碼位於拒收清單中,包括在建立發送後新增至清單的號碼)、quiet_hours(在收件人時區的上午 8 時至晚上 9 時以外到期)、sender_not_ready(短訊號碼已無法發送)或 outbound_tcpa_unconfirmed(在記錄機構 TCPA 確認前,通話已到期)。
{
"data": {
"agent_id": null,
"created_at": "2026-11-01T18:02:11.204Z",
"detail": "The send could not go out before its expires_at, so it was not sent late.",
"expires_at": "2026-11-03T17:30:00Z",
"external_id": "appointment-4815",
"from_number": "+15551234567",
"id": "6f1c0b8e-3a52-4c1f-9a0b-2f4f7d8a91c3",
"reason": "expired",
"send_at": "2026-11-03T17:00:00Z",
"source": "api",
"status": "skipped",
"to": "[REDACTED]",
"type": "sms"
},
"event_id": "2b0f6c43-74c9-4d43-a1f4-0d6a2f8e51a7",
"type": "scheduled.skipped"
}scheduled.failed
當 ThunderPhone 嘗試傳送但未能發出時送出。reason 為傳送本身的錯誤:SMS 錯誤代碼,例如短訊的 carrier_rejected;或通話的拒絕或失敗原因,例如封鎖目的地規則(例如 premium_rate)或 agent_deleted。Payload 與 scheduled.skipped 具有相同欄位。
| 欄位 | 類型 | 說明 |
|---|---|---|
id | string | 排程傳送的 id |
type | string | sms 或 call |
status | string | skipped 或 failed |
reason | string | 原因,如上所述;與傳送的 status_reason 相同 |
detail | string | 可讀說明 |
source | string | 建立傳送的來源:api |
external_id | string | null | 你為傳送設定的識別碼,或 null |
from_number | string | 發送號碼 |
to | string | 一律為 "[REDACTED]" |
agent_id | integer | null | 通話:智能體;短訊:null |
send_at, expires_at, created_at | timestamp | ISO 8601 |
語音事件
自訂語音建立採用非同步方式。這些非阻塞事件讓你可在取得最終結果時作出回應,而無需輪詢 複製語音詳情端點。
voice.ready 和 voice.failed 僅會傳送至設有 events: [] 的機構全域端點。它們不能選作明確事件篩選條件。
voice.ready
當自訂語音完成處理並可指派至智能體時發送。
{
"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
當自訂語音處理出現永久性失敗時發送。
{
"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"
}| 欄位 | 類型 | 說明 |
|---|---|---|
voice.id | string | 自訂語音公開 ID |
voice.name | string | 格式為 custom:<public_id> 的智能體語音值 |
voice.display_name | string | 面向機構顯示的語音名稱 |
voice.language | string | 複製語音的單一語言代碼 |
voice.gender | string | male、female 或空字串 |
voice.status | string | voice.ready 使用 ready;voice.failed 使用 failed |
voice.failure_reason | string | 成功時為空;失敗時為處理失敗詳情 |
voice.created_at, voice.updated_at | timestamp | ISO 8601 時間戳記 |
reason | string | 失敗詳情;僅於 voice.failed 出現 |
品質事件
call.graded
每當通話的 AI 評分作業完成時傳送。不會阻塞。
{
"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"
}| 欄位 | 類型 | 說明 |
|---|---|---|
agent_id | integer | null | 處理通話的智能體(如有指派) |
agent_name | string | null | 處理通話的智能體(如有指派) |
grade.id | integer | 評分 ID |
grade.score | integer | null | 0–100 |
grade.call_outcome | string | success、failure、unknown 或 no_conversation |
grade.summary | string | 單段摘要 |
grade.detected_issues | array | 評分器偵測到的問題字串 |
grade.status | string | 一律為 completed ——只有已完成的執行才會發出事件 |
grade.grader_model | string | 產生結果的評分器:heuristic-v1(或其他 ThunderPhone 規則式評分器)用於快速的暫定評分;thunderphone-grader 用於完整評分。這是 ThunderPhone 標籤,並非 AI 模型名稱 |
grade.graded_at, grade.created_at | timestamp | |
report | object | null | 面向客戶的通話報告:結果標籤、需要關注標記及原因、來電者、單行摘要、來電者體驗。在早期啟發式評分中,這會是 null 或欄位為佔位資料的 pending 報告;完整評分的事件會提供已完成的報告 |
call.data_extracted
每當結構化資料擷取成功完成時傳送,包括在 telephony.complete / web.complete 後的延遲重試,或透過
POST /v1/calls/{call_id}/extract 手動重新執行。不會阻塞。
在阻塞式擷取模式下,完成事件通常最多只會等待 75 秒的擷取預算。如果擷取工作程序遺失,正式環境的最終處理排程(每五分鐘一次)會在開始下一次擷取嘗試前,釋放 blocking_deadline_at 已過期的完成事件。其後如擷取成功,將以此事件另行傳送。
{
"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": "thunderphone-extractor",
"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"
}| 欄位 | 類型 | 說明 |
|---|---|---|
agent_id | 整數 | null | 處理此通話的智能體(如已指派) |
agent_name | 字串 | null | 處理此通話的智能體(如已指派) |
summary | 字串 | null | 智能體已啟用 生成通話摘要 時的完整通話摘要,因此延遲的擷取事件亦會提供未能在完成時限內產生的摘要;否則為 null。設有摘要但沒有擷取欄位的智能體絕不會發出此事件:請透過 GET /v1/calls/{call_id} 讀取延遲摘要 |
extracted_data.status | 字串 | 此事件一律為 completed |
extracted_data.fields | 物件 | 以已設定的擷取欄位鍵值為索引的值;無法取得的值為 null |
extracted_data.evidence | 物件 | 以擷取欄位為索引的證據。非 null 值包含已通過結構檢查的原始引述(最多 1,000 個字元)、speaker_role(caller 或 agent)及 turn_index;模型傳回的較長引述會被拒絕而不會截斷,而其欄位為 null 時,證據亦一律為 null |
extracted_data.verification | 字串 | 僅當獨立證據程序為每個候選欄位恰好傳回一個有效判定時,才會是 verified。unavailable 表示該程序失敗、逾時、預算不足,或傳回格式錯誤或不完整的輸出。完全無法使用的程序會保留具結構依據的值,以供客戶審核。對於部分輸出,系統會套用有效判定,並將每個未有恰好一個有效判定的候選欄位設為 null |
extracted_data.field_reasons | 物件 | 因結構依據或獨立驗證器而被設為 null 的欄位之原因,以欄位為索引 |
extracted_data.schema_version | 字串 | 此次擷取所用確切欄位架構的雜湊值 |
extracted_at | 時間戳記 | ISO 8601 完成時間 |
model | 字串 | 一律為 thunderphone-extractor:這是 ThunderPhone 為擷取模型所用的標籤,並非 AI 模型名稱 |
campaign.completed
當推廣活動由 running 轉為 completed 時傳送一次,無論是排程結束還是所有聯絡人均已進入終結狀態。執行器重試不會再次傳送事件。此組織層級的生命週期事件只會傳送至組織範圍端點,不會傳送至智能體範圍端點。不會阻塞。
{
"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,
"skipped": 4,
"remaining": 0
}
},
"event_id": "8d8f52ce-6b46-423f-9dde-cea0b91ec135",
"type": "campaign.completed"
}四個結果計數互不重疊,合計為 contacts_total:
completed 包含成功聯絡的聯絡人;no_answer 包含最終結果為未接聽的終止失敗/已耗盡嘗試次數聯絡人;failed 包含所有其他終止失敗/已耗盡嘗試次數聯絡人;而 remaining 包含待處理、已排程或正在通話的聯絡人。等待重試的聯絡人屬於 remaining,即使其最近一次嘗試的結果為未接聽亦然。系統會在一次性的完成快照前核對進行中的通話。started_at 為設定的活動開始時間;如未設定開始時間,則為活動建立時間。skipped 並非第五個分類:它計算 failed 之中被號碼類型篩選器在未進行通話前結束處理的聯絡人。
issue.reported
當建立問題報告時傳送——可由使用者在控制台提交(source: "user"),或由通話評分自動建立(source: "system")。不會阻塞。
{
"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"
}| 欄位 | 類型 | 說明 |
|---|---|---|
agent_id | integer | null | 處理通話的智能體(如已指派) |
agent_name | string | null | 處理通話的智能體(如已指派) |
issue_report.severity | string | critical、warning 或 info |
issue_report.status | string | open 或 resolved |
issue_report.source | string | user(從控制台提交)或 system(由評分建立) |
issue.escalated
當問題模式提交至 ThunderPhone 供團隊審核時傳送:在 向 ThunderPhone 回報 後,或當使用 AI 修正無法確認客戶端修正並自動轉交問題時。只有組織範圍端點會接收此事件。
{
"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"
}| 欄位 | 類型 | 說明 |
|---|---|---|
automatic | boolean | 自動升級為 true;手動升級為 false |
cluster_id | UUID | 已升級的問題模式 |
escalation_id | UUID | 升級記錄 |
status | string | 傳送事件時為 open |
這是通知,不是證據套件。請使用 cluster_id 將其與問題模式關聯。請參閱向 ThunderPhone 回報。
測試通話事件
test-call.completed
當一次
測試通話執行
達到終結狀態時傳送——completed 或 failed,包括在啟動時失敗且從未產生通話的執行。非阻塞式。適合將批次 CI 執行串接至你的聊天及通知系統。
{
"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"
}| 欄位 | 類型 | 說明 |
|---|---|---|
agent_id | integer | null | 處理通話的智能體(如已指派) |
agent_name | string | null | 處理通話的智能體(如已指派) |
test_call_run.target_type | string | agent 或 phone_number |
test_call_run.target_id | integer | 執行所針對的智能體 ID 或電話號碼 ID,與 target_type 相符 |
test_call_run.status | string | completed 或 failed |
test_call_run.call_id | integer | null | 如執行在發出通話前失敗,則為 null |
test_call_run.error_message | string | 成功時為空字串 |
警示事件
alert.triggered
當已啟用 傳送至開發者 Webhook 渠道的警示規則跨越其閾值時傳送。 非阻塞式。規則只會觸發一次,然後遵守其冷卻時間;因此,持續違反條件時,每個冷卻時段只會產生一個事件。
{
"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"
}| 欄位 | 類型 | 說明 |
|---|---|---|
event_id(位於 data) | UUID | 警示的 觸發 ID——與外層封包的傳送 event_id 不同 |
rule_id, rule_name | UUID, string | 已觸發的規則 |
metric | string | success_rate、failure_rate、avg_score、call_volume 或 suite_regression |
comparator | string | lt、lte、gt 或 gte |
metric_value | number | 規則觸發時,該指標在時段內的數值 |
threshold | number | 已設定的閾值 |
window_hours | integer | 回溯評估時段 |
fired_at | timestamp |
請參閱警示指南,了解如何建立規則、指標、冷卻時間,以及電郵/Slack 渠道。
電話號碼事件
phone_number.spam_risk_changed
當垃圾電話標籤監察功能(可透過支援團隊申請的付費附加功能)偵測到受監察號碼的垃圾電話風險升至 medium 或 high 時發送(可由 low 升至該等級別、尚未有讀數,或由 medium 升至 high)。不會阻礙其他操作。持續被標記的號碼不會再次發送;已回復至 low 後日後再次被標記的號碼則會發送。
此事件不包含智能體內容,因此只有全組織端點會接收。組織擁有人及管理員亦會收到電郵。
{
"data": {
"checked_at": "2026-10-21T14:41:07+00:00",
"phone_number": "+13125550100",
"phone_number_id": 412,
"previous_spam_risk": "low",
"scores": {
"connection": 31,
"engagement": 40,
"maturity": 82,
"sentiment": 22
},
"spam_category": "Telemarketer",
"spam_risk": "high"
},
"event_id": "6f1c2d3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f",
"type": "phone_number.spam_risk_changed"
}| 欄位 | 類型 | 說明 |
|---|---|---|
phone_number | string | 號碼,採用 E.164 格式 |
phone_number_id | integer | null | 其於電話號碼中的 id |
spam_risk | string | medium 或 high |
previous_spam_risk | string | null | 上次讀數的風險;首次讀取前為 null |
spam_category | string | null | 電訊商可能顯示的標籤,例如 Telemarketer 或 Survey。請視為自由文字 |
scores | object | 每項為 0 至 100,或在通話量未足夠前為 null:maturity(號碼的建立程度)、connection(人們是否接聽)、engagement(是否持續通話)、sentiment(是否封鎖或舉報) |
checked_at | timestamp | ThunderPhone 讀取結果的時間 |
遷移事件
migration.call.complete
當透過
POST /v1/migrations/{id}/calls 建立的通話結束時發送,無論由哪個平台接聽。此事件不會阻塞操作。通話結束後最多約 5 分鐘內送達。data 包含
telephony.complete 的所有欄位,以及一個 migration 區塊。由 ThunderPhone 建立的通話亦會如常發送 telephony.complete,並使用相同的 call_id。由其他平台接聽的通話,其 answered_by 為 null。其他平台的通話如在 2 小時後仍未結束,或其遷移先完成或遺失金鑰,將以
status: "unknown" 及不含逐字稿的形式發送。
{
"data": {
"agent_id": 42,
"agent_name": "Front desk",
"answered_by": null,
"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"
}| 欄位 | 類型 | 說明 |
|---|---|---|
migration.id | UUID | 遷移項目 |
migration.routing_id | UUID | 已路由的通話,即你發出通話時傳回的資料 |
migration.arm | string | ours(由 ThunderPhone 發出)或 vendor(由其他平台發出) |
migration.vendor | string | retell、vapi、elevenlabs 或 bland |
migration.vendor_call_id | string | null | 其他平台的通話 ID;ours 時為 null |
migration.metadata | object | 發出通話時傳送的 metadata |
migration.vendor_cost_usd | string | null | 其他平台所報告的通話費用(如有提供) |
call_id | integer | null | ThunderPhone 通話 ID;vendor 時為 null |
status | string | 對於 vendor:接聽者有說話時為 completed,沒有說話時為 failed,如上所述則為 unknown。對於 ours:與 telephony.complete 相同 |
對於 vendor 通話,ThunderPhone 不會提供計費或資料擷取資料:
billable_minutes、billing_total_cents 和 extracted_data 為 null,
product 和 voice 為空值,recording_mode 為 vendor,而
recording_url 則為其他平台提供的連結(如有)。
migration.rollback
當遷移的逐步切換自動將所有通話轉回另一個平台時發送:15 分鐘內有 3 個通話未能連接至 ThunderPhone、轉送至 ThunderPhone 的 2 個通話在智能體接聽前結束,或 ThunderPhone 的任務結果率比另一個平台低於設定差距以上。非阻塞,每次回復時發送一次。發送後,ThunderPhone 的 通話佔比為 0%,而遷移會暫停,直至有人在智能體的「遷移」分頁中恢復遷移。酬載不包含電話號碼、對話轉錄或通話 ID。
{
"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"
}| 欄位 | 類型 | 說明 |
|---|---|---|
migration_id | UUID | 遷移 |
vendor | 字串 | retell、vapi、elevenlabs 或 bland |
reason | 字串 | ours_failed_burst(15 分鐘內 3 次連接失敗)、dropped_calls(30 分鐘內 2 個通話在智能體接聽前結束),或 rate_gap(雙方各自至少有 rollback_min_calls 個已評分通話時的任務結果率差距) |
previous_percent | 整數 | 回復前 ThunderPhone 的通話佔比 |
ours_percent | 整數 | 固定為 0 |
step | 整數 | null | 當時所在的排程步驟(以 0 為起點) |
ours / theirs | 物件 | null | 目前步驟中的已評分通話及其成功率;如該步驟的通話數量不足,theirs 可能為最近 30 日的資料。如沒有資料則為 null |
ours_failed | 整數 | 最近 15 分鐘內計算在內的連接失敗次數 |
dropped | 整數 | 最近 30 分鐘內計算為中斷的通話數目 |
rolled_back_at | 時間戳記 |