ThunderPhone v3 現已上線。自助開通,價格低至每分鐘 2¢。查看公告

Webhooks

事件目錄

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_idinteger | null已指派時,處理此通話的智能體
agent_namestring | null已指派時,處理此通話的智能體
returning_callobject僅當此號碼在過去 30 日內曾致電此來電者時提供:較早前通話的 call_id、agent_id、started_at 及 outcome。參閱 回撥
sip_headersobject僅當通話附帶 X-* 或 User-to-User SIP 標頭時提供(SIP 位址及手動 SIP 連線):以小寫表示的標頭名稱 → 值。參閱 SIP 標頭

telephony.complete

當來電或撥出電話結束時發送。非阻塞式。 包括逐字稿、錄音 URL(如適用)及收費摘要。Payload schema 請參閱 telephony.complete / web.complete。

欄位類型說明
agent_idinteger | null處理通話的智能體(如已指派)
agent_namestring | 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_idinteger | null處理通話的智能體(如已指派)
agent_namestring | 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_idinteger | null處理通話的智能體(如已指派)
agent_namestring | null處理通話的智能體名稱(如已指派)
positioninteger回合在通話記錄中的索引——用於排序的穩定識別碼
rolestringassistant(智能體語音)或 user(來電者語音)
textstring發送當刻所知的回合逐字稿文字
entry_typestring底層記錄項目類型:completion(智能體)或 user_turn / span(來電者)
start_ms, end_msinteger自通話開始起計的音訊偏移量(毫秒);僅在發送當刻已知播放時間時提供

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_idinteger | null處理通話的智能體(如已指派)
agent_namestring | null處理通話的智能體名稱(如已指派)

web.complete

telephony.complete 的網頁渠道對應事件,涵蓋網頁小工具通話(direction: "web")及建構器咪高峰測試通話 (direction: "test")。非阻塞式。Payload 格式與 telephony.complete 相同,另加 origin_domain, 而 from_number 設為 "web"。

欄位類型說明
agent_idinteger | null處理通話的智能體(如已指派)
agent_namestring | null處理通話的智能體名稱(如已指派)

web.tool

telephony.tool 的網頁渠道對應事件。data 使用 origin_domain,而非 from_number / to_number。

欄位類型說明
agent_idinteger | null處理通話的智能體(如已指派)
agent_namestring | null處理通話的智能體名稱(如已指派)

web.turn

telephony.turn 的網頁渠道對應事件,涵蓋網頁小工具通話及建構器咪高峰測試通話。Payload 格式相同,但以 origin_domain 取代 from_number / to_number。與 telephony.turn 相同,此事件需要明確訂閱——絕不會透過空白 events 陣列傳送。

欄位類型說明
agent_idinteger | null處理通話的智能體(如已指派)
agent_namestring | 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_idinteger已轉接的通話
agent_idinteger | null已指派時,處理該通話的智能體
agent_namestring | null已指派時,處理該通話的智能體
transfer_outcomestringrefer_accepted:電訊商已接手通話。bridged:ThunderPhone 自行維持來電者與目的地之間的連線,原因可能是電訊商拒絕冷轉接,或暖轉接的智能體已退出。bridge_unanswered:電訊商拒絕冷轉接,而目的地未有接聽 ThunderPhone 自行撥出的通話。failed:轉接未能完成,通話已結束
destinationstring | null通話轉接至的號碼
sip_statusinteger | null電訊商拒絕冷轉接時的 SIP 狀態:403(例如不支援通話轉接的 Twilio trunk)、405 或 501。如電訊商沒有拒絕,則為 null
bridge_kindstring | null僅適用於 bridged:cold_fallback(ThunderPhone 連接的被拒冷轉接)或 warm(智能體退出後暖轉接中的兩位真人)
bridge_secondsinteger | null僅適用於 bridged:ThunderPhone 計費的橋接時間,以秒為單位
bridge_total_centsinteger | 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_idinteger已計費的通話
agent_idinteger | null已指派智能體時,處理該通話的智能體
agent_namestring | null已指派智能體時,處理該通話的智能體
reasonstringsettled:通話費用。adjusted:費用結算後到達並提高費用的用量(費用絕不會下調)
billing_seqinteger費用為 1,其後每次增加依序為 2、3、...。收到的最高值即為通話目前的計費資料
billable_minutesnumber計費分鐘數,四捨五入至最接近的四分一分鐘
billing_total_centsinteger通話至今已收取的所有美元美仙費用,扣除任何免費通話額度後計算,包括 adjusted 增加額
adjustment_centsinteger | 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_idinteger通話
agent_idinteger | null已指派時,處理通話的智能體
agent_namestring | null已指派時,處理通話的智能體
directionstring通話方向,與通話物件中的定義一致
statusstring通話到達的階段;請參閱下表
occurred_attimestamp發生時間
hold_secondsinteger | 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 具有相同欄位。

欄位類型說明
idstring排程傳送的 id
typestringsms 或 call
statusstringskipped 或 failed
reasonstring原因,如上所述;與傳送的 status_reason 相同
detailstring可讀說明
sourcestring建立傳送的來源:api
external_idstring | null你為傳送設定的識別碼,或 null
from_numberstring發送號碼
tostring一律為 "[REDACTED]"
agent_idinteger | null通話:智能體;短訊:null
send_at, expires_at, created_attimestampISO 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.idstring自訂語音公開 ID
voice.namestring格式為 custom:<public_id> 的智能體語音值
voice.display_namestring面向機構顯示的語音名稱
voice.languagestring複製語音的單一語言代碼
voice.genderstringmale、female 或空字串
voice.statusstringvoice.ready 使用 ready;voice.failed 使用 failed
voice.failure_reasonstring成功時為空;失敗時為處理失敗詳情
voice.created_at, voice.updated_attimestampISO 8601 時間戳記
reasonstring失敗詳情;僅於 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_idinteger | null處理通話的智能體(如有指派)
agent_namestring | null處理通話的智能體(如有指派)
grade.idinteger評分 ID
grade.scoreinteger | null0–100
grade.call_outcomestringsuccess、failure、unknown 或 no_conversation
grade.summarystring單段摘要
grade.detected_issuesarray評分器偵測到的問題字串
grade.statusstring一律為 completed ——只有已完成的執行才會發出事件
grade.grader_modelstring產生結果的評分器:heuristic-v1(或其他 ThunderPhone 規則式評分器)用於快速的暫定評分;thunderphone-grader 用於完整評分。這是 ThunderPhone 標籤,並非 AI 模型名稱
grade.graded_at, grade.created_attimestamp
reportobject | 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_idinteger | null處理通話的智能體(如已指派)
agent_namestring | null處理通話的智能體(如已指派)
issue_report.severitystringcritical、warning 或 info
issue_report.statusstringopen 或 resolved
issue_report.sourcestringuser(從控制台提交)或 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"
}
欄位類型說明
automaticboolean自動升級為 true;手動升級為 false
cluster_idUUID已升級的問題模式
escalation_idUUID升級記錄
statusstring傳送事件時為 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_idinteger | null處理通話的智能體(如已指派)
agent_namestring | null處理通話的智能體(如已指派)
test_call_run.target_typestringagent 或 phone_number
test_call_run.target_idinteger執行所針對的智能體 ID 或電話號碼 ID,與 target_type 相符
test_call_run.statusstringcompleted 或 failed
test_call_run.call_idinteger | null如執行在發出通話前失敗,則為 null
test_call_run.error_messagestring成功時為空字串

警示事件

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_nameUUID, string已觸發的規則
metricstringsuccess_rate、failure_rate、avg_score、call_volume 或 suite_regression
comparatorstringlt、lte、gt 或 gte
metric_valuenumber規則觸發時,該指標在時段內的數值
thresholdnumber已設定的閾值
window_hoursinteger回溯評估時段
fired_attimestamp

請參閱警示指南,了解如何建立規則、指標、冷卻時間,以及電郵/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_numberstring號碼,採用 E.164 格式
phone_number_idinteger | null其於電話號碼中的 id
spam_riskstringmedium 或 high
previous_spam_riskstring | null上次讀數的風險;首次讀取前為 null
spam_categorystring | null電訊商可能顯示的標籤,例如 Telemarketer 或 Survey。請視為自由文字
scoresobject每項為 0 至 100,或在通話量未足夠前為 null:maturity(號碼的建立程度)、connection(人們是否接聽)、engagement(是否持續通話)、sentiment(是否封鎖或舉報)
checked_attimestampThunderPhone 讀取結果的時間

遷移事件

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.idUUID遷移項目
migration.routing_idUUID已路由的通話,即你發出通話時傳回的資料
migration.armstringours(由 ThunderPhone 發出)或 vendor(由其他平台發出)
migration.vendorstringretell、vapi、elevenlabs 或 bland
migration.vendor_call_idstring | null其他平台的通話 ID;ours 時為 null
migration.metadataobject發出通話時傳送的 metadata
migration.vendor_cost_usdstring | null其他平台所報告的通話費用(如有提供)
call_idinteger | nullThunderPhone 通話 ID;vendor 時為 null
statusstring對於 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_idUUID遷移
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時間戳記

相關內容