事件目錄

每個 webhook 主體均包含一個 type 欄位，其值為本頁其中一種事件 類型。當你訂閱一個 端點時，events 陣列必須包含你所需的 事件類型（或留空以訂閱所有事件）。

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

• 端點傳送一律為非阻塞式通知， 並支援重試：請回應任何 2xx；封套會包含一個 event_id，可用作去重。
• 阻塞式交換僅會在 舊版單一 URL webhook上執行：包括 telephony.incoming / web.incoming 設定請求（webhook 模式號碼及小工具金鑰，逾時時間為 10 秒），以及 webhook 模式的 工具派送。你的回應會影響即時通話。

以下範例負載顯示端點封套的傳輸順序 （欄位按字母排序：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"
}

telephony.complete

當來電或去電結束時發送。非阻塞式。 包括逐字稿、可用時的錄音網址，以及帳單摘要。Payload 結構請參閱 telephony.complete / web.complete。

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

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 為空值。

web.complete

telephony.complete 的網頁渠道對應事件，涵蓋網頁小工具通話（direction: "web"）及建構器麥克風測試通話 （direction: "test"）。非阻塞式。Payload 結構與 telephony.complete相同，但會額外包含 origin_domain， 並將 from_number 設為 "web"。

web.tool

telephony.tool 的網頁渠道對應事件。data 會包含 origin_domain，而非 from_number ／ to_number。

語音事件

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

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

品質事件

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

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

測試通話事件

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

警示事件

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

參閱警示指南，了解如何建立規則、指標、冷卻時間及電郵／Slack 渠道。

相關內容