Webhook

Webhook の仕組み

通話イベントが発生すると、OneInbox はイベントペイロードを含む HTTP POST をサーバーに送信します。サーバーは数秒以内に 2xx で応答する必要があります — 応答がない場合、OneInbox は再送します。 Webhook を設定すれば、GET /v1/calls/<id> を繰り返しポーリングする必要はありません。OneInbox がイベント発生の瞬間にデータをプッシュします。

Webhook を作成する

サーバー上の URL と受信したいイベントを指定して Webhook をセットアップします。OneInbox はそれらのイベントが発火するたびにその URL に POST リクエストを送信します。

curl -X POST https://api-tokyo.oneinbox.ai/v1/webhooks \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Call events",
    "url": "https://your-server.com/webhooks/oneinbox",
    "events": ["call.started", "call.ended", "call.analyzed", "call.failed", "call.recording.available", "transcript.partial", "transcript.final"]
  }'

{
  "id": "wh_abc123",
  "name": "Call events",
  "url": "https://your-server.com/webhooks/oneinbox",
  "events": ["call.started", "call.ended", "transcript.final"]
}

id を保存しておいてください — Webhook の更新や削除に必要です。

サポートされているイベント

イベント	発火タイミング
`call.started`	通話が接続し、エージェントがセッションを開始したとき
`call.ended`	通話が終了したとき — エージェントまたは発信者がハングアップ
`call.analyzed`	通話後に AI 分析（サマリー、結果）が準備完了したとき
`call.failed`	通話の接続に失敗したとき
`call.recording.available`	通話録音が準備完了してアクセス可能になったとき
`transcript.partial`	アクティブな通話中の部分的なトランスクリプト更新
`transcript.final`	完全なトランスクリプトが準備完了したとき（`call.ended` の後に発火）

イベントペイロード

`call.started`

通話が接続し、エージェントがセッションを開始したときに発火します。通話開始時刻をログに記録したり、CRM で「通話中」の更新をトリガーするために使用します。

{
  "event": "call.started",
  "call_id": "call_abc123",
  "agent_id": "agt_abc123",
  "to_number": "+919876543210",
  "from_number": "+15739693824",
  "created_at": "2026-06-01T10:00:00Z"
}

`call.ended`

通話が終了したときに発火します。このペイロードには AI が生成した結果とサマリーが含まれます — CRM 更新、リードルーティング、レポートに最もよく使われるイベントです。

{
  "event": "call.ended",
  "call_id": "call_abc123",
  "agent_id": "agt_abc123",
  "status": "completed",
  "duration_seconds": 87,
  "to_number": "+919876543210",
  "from_number": "+15739693824",
  "outcome": "Appointment Booked",
  "ai_summary": "Caller agreed to a product demo on Thursday at 3pm.",
  "analysis": {
    "summary": "Caller agreed to a product demo on Thursday at 3pm."
  }
}

`call.analyzed`

通話終了後、AI がサマリーと結果の生成を完了したときに発火します。通話結果に基づいた CRM 更新やリードルーティングをトリガーするために使用します。

{
  "event": "call.analyzed",
  "call_id": "call_abc123",
  "agent_id": "agt_abc123",
  "outcome": "Appointment Booked",
  "ai_summary": "Caller agreed to a product demo on Thursday at 3pm."
}

`call.failed`

通話の接続に失敗したときに発火します。失敗のログ記録、リトライのトリガー、チームへのアラートに使用します。

{
  "event": "call.failed",
  "call_id": "call_abc123",
  "agent_id": "agt_abc123",
  "to_number": "+919876543210",
  "from_number": "+15739693824",
  "reason": "no-answer"
}

`call.recording.available`

通話録音が処理されてアクセス可能になったときに発火します。通話後に録音を保存または共有するために使用します。

{
  "event": "call.recording.available",
  "call_id": "call_abc123",
  "recording_url": "https://storage.oneinbox.ai/recordings/call_abc123.mp3"
}

`transcript.partial`

部分的なトランスクリプト更新とともにアクティブな通話中に発火します。リアルタイムモニタリングやライブエージェントアシストに使用します — 部分的なトランスクリプトは通話が続くにつれて変わる場合があることに注意してください。

{
  "event": "transcript.partial",
  "call_id": "call_abc123",
  "messages": [
    { "role": "agent", "content": "Hi! How can I help you today?" },
    { "role": "user",  "content": "I'd like to book a demo." }
  ]
}

`transcript.final`

完全なトランスクリプトが準備完了したら call.ended の後に発火します。データベースへの記録や CRM への送信など、完全なメッセージごとの会話ログが必要な場合に使用します。

{
  "event": "transcript.final",
  "call_id": "call_abc123",
  "messages": [
    { "role": "agent", "content": "Hi! How can I help you today?" },
    { "role": "user",  "content": "I'd like to book a demo." },
    { "role": "agent", "content": "Of course! Let me get that booked for you." }
  ]
}

Webhook をテストする

本番稼働前にサーバーがイベントを正しく受信していることを確認するためにテスト配信を送信します：

curl -X POST https://api-tokyo.oneinbox.ai/v1/webhooks/<webhook_id>/test \
  -H "Authorization: Bearer <api_key>"

サーバーはサンプルペイロードを含むテスト POST を受信するはずです。サーバーのログを確認して、受信できていてエンドポイントが 2xx を返していることを確認してください。

通話ごとの Webhook 上書き

グローバルな Webhook 設定を変更せずに、特定の通話のイベントを別の URL に送ることができます。これは異なるキャンペーンやバッチを別々のダウンストリームシステムにルーティングする場合に便利です — 例えばインバウンド通話用の URL とアウトバウンド通話用の URL を分ける場合。通話を作成するときに webhook_url を渡します：

curl -X POST https://api-tokyo.oneinbox.ai/v1/calls \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<agent_id>",
    "to_number": "+919876543210",
    "from_number": "+15739693824",
    "webhook_url": "https://your-server.com/this-campaign-only"
  }'

この通話のイベントは、設定済みのグローバル Webhook の代わりに（または追加で）webhook_url に送られます。

Webhook を管理する

すべての Webhook を一覧表示

アカウント内のすべての Webhook を取得します。更新または削除が必要な Webhook の id を見つけるために使用します。

curl https://api-tokyo.oneinbox.ai/v1/webhooks \
  -H "Authorization: Bearer <api_key>"

Webhook を更新する

Webhook の URL、名前、イベント、またはステータスを変更します。

curl -X PATCH https://api-tokyo.oneinbox.ai/v1/webhooks/<webhook_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "events": ["call.started", "call.ended", "transcript.final"] }'

フィールド	内容
`name`	Webhook の名前変更
`url`	配信エンドポイントの変更
`events`	購読イベントの全リストを置換
`status`	`"active"` または `"inactive"` — Webhook を削除せずに配信を一時停止

Webhook を削除する

Webhook を永続的に削除します。OneInbox はその URL へのイベント送信を即座に停止します。

curl -X DELETE https://api-tokyo.oneinbox.ai/v1/webhooks/<webhook_id> \
  -H "Authorization: Bearer <api_key>"

配信履歴を確認する

Webhook の配信試行ログを取得します。特定のイベントがサーバーに届いたか確認したり、配信失敗を診断するのに便利です。最新の試行から順に返され、各行に response_status、response_body、error が含まれます。

curl "https://api-tokyo.oneinbox.ai/v1/webhooks/<webhook_id>/deliveries?limit=50" \
  -H "Authorization: Bearer <api_key>"

API リファレンス

Webhook 作成 · Webhook 一覧 · Webhook 更新 · テスト配信

はじめる

通話を行う

エージェントを設定する

監視・統合

コアコンセプト

Webhook の仕組み

Webhook を作成する

サポートされているイベント

イベントペイロード

`call.started`

`call.ended`

`call.analyzed`

`call.failed`

`call.recording.available`

`transcript.partial`

`transcript.final`

Webhook をテストする

通話ごとの Webhook 上書き

Webhook を管理する

すべての Webhook を一覧表示

Webhook を更新する

Webhook を削除する

配信履歴を確認する

API リファレンス

​Webhook の仕組み

​Webhook を作成する

​サポートされているイベント

​イベントペイロード

​call.started

​call.ended

​call.analyzed

​call.failed

​call.recording.available

​transcript.partial

​transcript.final

​Webhook をテストする

​通話ごとの Webhook 上書き

​Webhook を管理する

​すべての Webhook を一覧表示

​Webhook を更新する

​Webhook を削除する

​配信履歴を確認する

​API リファレンス

Webhook の仕組み

Webhook を作成する

サポートされているイベント

イベントペイロード

`call.started`

`call.ended`

`call.analyzed`

`call.failed`

`call.recording.available`

`transcript.partial`

`transcript.final`

Webhook をテストする

通話ごとの Webhook 上書き

Webhook を管理する

すべての Webhook を一覧表示

Webhook を更新する

Webhook を削除する

配信履歴を確認する

API リファレンス