ThunderPhone 2.0 正式登場。自助開通，價格低至每分鐘 2¢。查看公告
立即開始

Webhooks

View as Markdown
Open in
ClaudeChatGPTCursor

事件目錄

ThunderPhone 發出的所有 Webhook 事件類型。

每個 webhook 內容均設有 type 欄位，其值為本頁其中一種事件 類型。當你訂閱某個 端點時，events 陣列必須包含你所需的 事件類型（或留空以訂閱所有事件—— 惟每輪事件 telephony.turn / web.turn 除外；這些事件只會傳送至明確列出它們的 端點）。

這些事件透過兩種傳送方式傳遞：

以下範例內容顯示端點封套的傳輸順序 （索引鍵按字母排序：data、event_id、type）；舊版傳送會帶有相同的 data，但不包括 event_id。

通話事件

telephony.incoming

當來電到達你的其中一個電話號碼時發送。端點傳送為針對每一個來電的發送後不等待通知，無論該號碼已設定智能體還是 webhook。未指派智能體的號碼，亦會透過舊版 webhook 收到阻塞式設定請求——完整請求／回應結構請參閱 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整數 | null已處理通話的智能體（如已指派）
agent_name字串 | null已處理通話的智能體（如已指派）

telephony.complete

當來電或撥出電訊通話結束時發送。非阻塞。 包括逐字稿、可用時的錄音 URL，以及收費摘要。payload 結構請參閱 telephony.complete / web.complete。

欄位類型說明
agent_id整數 | null已處理通話的智能體（如已指派）
agent_name字串 | null已處理通話的智能體（如已指派）

telephony.tool

當電訊通話呼叫函式工具後發送。非阻塞稽核通知——傳送此事件時工具已執行；僅涵蓋你自己的函式工具（不包括內建、知識庫、應用程式連線或 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 是已執行的結果：成功時為 {"status": <http status>, "response": <your endpoint's JSON>}，失敗時為 {"status": <status>, "error": "<message>"}。

欄位類型說明
agent_id整數 | null已處理通話的智能體（如已指派）
agent_name字串 | 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整數 | null已處理通話的智能體（如已指派）
agent_name字串 | null已處理通話的智能體（如已指派）
position整數輪次在通話記錄中的索引——用於排序的穩定識別碼
role字串assistant（智能體語音）或 user（來電者語音）
text字串發送當刻所知的輪次逐字稿文字
entry_type字串底層記錄項目類型：completion（智能體），或 user_turn / span（來電者）
start_ms, end_ms整數自通話開始起計的音訊偏移量（毫秒）；僅在發送當刻已知播放時間時提供

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整數 | null已處理通話的智能體（如已指派）
agent_name字串 | null已處理通話的智能體（如已指派）

web.complete

telephony.complete 的網頁頻道對應事件，涵蓋網頁小工具通話（direction: "web"）和建構工具咪高峰測試通話（direction: "test"）。非阻塞。payload 結構與 telephony.complete 相同，另加 origin_domain，並將 from_number 設為 "web"。

欄位類型說明
agent_id整數 | null已處理通話的智能體（如已指派）
agent_name字串 | null已處理通話的智能體（如已指派）

web.tool

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

欄位類型說明
agent_id整數 | null已處理通話的智能體（如已指派）
agent_name字串 | null已處理通話的智能體（如已指派）

web.turn

telephony.turn 的網頁頻道對應事件，涵蓋網頁小工具通話和建構工具咪高峰測試通話。payload 結構相同，但使用 origin_domain，而非 from_number / to_number。與 telephony.turn 一樣，必須明確訂閱——絕不會透過空白的 events 陣列傳送。

欄位類型說明
agent_id整數 | null已處理通話的智能體（如已指派）
agent_name字串 | null已處理通話的智能體（如已指派）

語音事件

自訂語音建立為非同步操作。這些非阻塞事件讓你可在取得最終結果時作出回應，而毋須輪詢複製語音詳情端點。

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…"
    }
  },
  "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）
grade.graded_at, grade.created_attimestamp

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": "gemini-2.5-flash"
  },
  "event_id": "4d79ef1d-c2b1-4ed6-85b8-8326bd2895ef",
  "type": "call.data_extracted"
}
欄位類型說明
agent_idinteger | null處理通話的智能體（如已指派）
agent_namestring | null處理通話的智能體（如已指派）
extracted_data.statusstring此事件永遠為 completed
extracted_data.fieldsobject以已設定擷取欄位鍵作索引的值；不可用的值為 null
extracted_data.evidenceobject以擷取欄位作索引的證據。非 null 值包括經精確結構檢查的引述（最多 1,000 個字元）、speaker_role（caller 或 agent）及 turn_index；模型回傳較長的引述會被拒絕而非截斷；當其欄位為 null 時，證據亦為 null
extracted_data.verificationstring只有獨立證據程序為每個候選欄位回傳剛好一個有效判定時，才會是 verified。unavailable 表示程序失敗、逾時、預算不足，或回傳格式錯誤或不完整的輸出。完全不可用的程序會保留具結構依據的值供客戶審核。若輸出不完整，系統會套用有效判定，並將每個沒有剛好一個有效判定的候選值設為 null
extracted_data.field_reasonsobject因結構依據或獨立驗證器而設為 null 的欄位原因，按欄位索引
extracted_data.schema_versionstring此次擷取所使用的精確欄位綱要雜湊值
extracted_attimestampISO 8601 完成時間
modelstring用於擷取的模型

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,
      "remaining": 0
    }
  },
  "event_id": "8d8f52ce-6b46-423f-9dde-cea0b91ec135",
  "type": "campaign.completed"
}

四個結果計數互不重疊，合計為 contacts_total： completed 包含成功聯絡的聯絡人；no_answer 包含最終結果為無人接聽的 終止失敗／重試耗盡聯絡人；failed 包含所有其他終止失敗／重試耗盡聯絡人； 而 remaining 則包含待處理、已排程或正在通話的聯絡人。等待重試的聯絡人 屬於 remaining，即使其最近一次嘗試的結果為無人接聽。系統會在僅發送一次的 完成快照前核對進行中的通話。started_at 為已設定的推廣活動開始時間；如未設定 開始時間，則為推廣活動建立時間。

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 渠道，請參閱警示指南。

相關內容

telephony.incoming / web.incoming

你必須回應的阻塞式入站通話資料內容。

telephony.complete / web.complete

通話後的逐字稿及指標。

Webhook 端點

為 URL 訂閱這些事件中的指定部分。

函式工具

telephony.tool／web.tool 事件的產生方式。