イベントカタログ

ThunderPhone が送信するすべてのWebhookイベントタイプ。

すべてのWebhook本文には type フィールドがあり、その値はこのページに記載されているイベントタイプのいずれかです。エンドポイントを登録する場合、events 配列には必要なイベントタイプを含める必要があります（すべてを登録する場合は空にします。ただし、ターンごとのイベントであるtelephony.turn / web.turnは例外で、明示的に指定したエンドポイントにのみ配信されます）。

これらのイベントには、次の2つの配信形式があります。

エンドポイント配信は常に、再試行を伴う非ブロッキング通知です。任意の2xxで応答してください。重複排除に使用するevent_idがエンベロープに含まれます。
ブロッキング交換は、レガシーの単一URL Webhookでのみ実行されます。対象は、 telephony.incoming / web.incoming の設定リクエスト（Webhookモードの電話番号とウィジェットキー、タイムアウトは10秒）およびWebhookモードのツールディスパッチです。応答内容が進行中の通話を決定します。

以下のペイロード例では、エンドポイントエンベロープをワイヤ形式の順序（キーはアルファベット順：data、event_id、type）で示します。レガシー配信では、event_idなしで同じdataが送信されます。

通話イベント

`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`

着信または発信の電話通話が終了したときに送信されます。非ブロッキングです。文字起こし、利用可能な場合は録音 URL、請求概要が含まれます。ペイロードスキーマについては、 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>"} です。

`telephony.turn`

電話通話が進行中に、発話を含む各ターンの発生時に 1 回ずつ送信されます。エージェントが発話した応答と、発信者の文字起こしターンが対象です。ポーリングの代わりに通常の 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"
}

フィールド	型	説明
`position`	integer	通話履歴内のターンのインデックス。順序付けに使用する安定した識別子
`role`	string	`assistant`（エージェントの発話）または `user`（発信者の発話）
`text`	string	送信時点で認識されているターンの文字起こしテキスト
`entry_type`	string	基となる履歴エントリタイプ。`completion`（エージェント）、または `user_turn` / `span`（発信者）
`start_ms`, `end_ms`	integer	通話開始からの音声オフセット（ミリ秒）。送信時点ですでに再生タイミングが判明している場合にのみ存在

`web.incoming`

telephony.incoming の Web チャネル版です。 Web ウィジェットセッションまたはビルダーのマイクテスト通話が開始されたときに送信されます。エンドポイント配信は、すべての Web セッションに対するファイア・アンド・フォーゲット通知です。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 の Web チャネル版です。Web ウィジェット通話（direction: "web"）とビルダーのマイクテスト通話（direction: "test"）を対象とします。非ブロッキングです。 telephony.completeと同じペイロード形式に加え、origin_domain が含まれ、from_number は "web" に設定されます。

`web.tool`

telephony.tool の Web チャネル版です。data には from_number / to_number ではなく origin_domain が含まれます。

`web.turn`

telephony.turn の Web チャネル版です。Web ウィジェット通話とビルダーのマイクテスト通話を対象とします。ペイロード形式は同じですが、from_number / to_number の代わりに origin_domain が含まれます。telephony.turn と同様に、明示的な購読が必要です。空の 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…"
    }
  },
  "event_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "type": "call.graded"
}

フィールド	型	説明
`grade.id`	integer	評価 ID
`grade.score`	integer \| null	0～100
`grade.call_outcome`	string	`success`、`failure`、`unknown`、または `no_conversation`
`grade.summary`	string	1 段落の要約
`grade.detected_issues`	array	評価器によって検出された問題の文字列
`grade.status`	string	常に `completed` — 完了した実行のみが送信されます
`grade.grader_model`	string	結果を生成した評価器（例: `heuristic-v1`）
`grade.graded_at`, `grade.created_at`	timestamp

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

フィールド	型	説明
`issue_report.severity`	string	`critical`、`warning`、または `info`
`issue_report.status`	string	`open` または `resolved`
`issue_report.source`	string	`user`（ダッシュボードから登録）または `system`（評価により作成）

テスト通話イベント

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

フィールド	型	説明
`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`

開発者向けウェブフックに配信チャネルが有効なアラートルールが、しきい値を超えたときに送信されます。非ブロッキングです。ルールは一度発火した後、クールダウンに従います。そのため、継続的なしきい値違反では、クールダウンウィンドウごとに1件のイベントが生成されます。

{
  "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、文字列	発火したルール
`metric`	文字列	`success_rate`、`failure_rate`、`avg_score`、`call_volume`、または `suite_regression`
`comparator`	文字列	`lt`、`lte`、`gt`、または `gte`
`metric_value`	数値	ルールが発火した時点のウィンドウ内における指標値
`threshold`	数値	設定されたしきい値
`window_hours`	整数	直近の評価ウィンドウ
`fired_at`	タイムスタンプ

ルール、指標、クールダウン、メール / Slack チャネルの作成については、アラートガイドを参照してください。