メインコンテンツへスキップ

​
Webhook の仕組み

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

​
Webhook を作成する

サーバー上の URL と受信したいイベントを指定して Webhook をセットアップします。OneInbox はそれらのイベントが発火するたびにその URL に POST リクエストを送信します。 
curl -X POST https://api.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.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.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.oneinbox.ai/v1/webhooks \
  -H "Authorization: Bearer <api_key>"

​
Webhook を更新する

Webhook の URL、名前、イベント、またはステータスを変更します。 
curl -X PATCH https://api.oneinbox.ai/v1/webhooks/<webhook_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "events": ["call.started", "call.ended", "transcript.final"] }'
フィールド内容
nameWebhook の名前変更
url配信エンドポイントの変更
events購読イベントの全リストを置換
status"active" または "inactive" — Webhook を削除せずに配信を一時停止

​
Webhook を削除する

Webhook を永続的に削除します。OneInbox はその URL へのイベント送信を即座に停止します。 
curl -X DELETE https://api.oneinbox.ai/v1/webhooks/<webhook_id> \
  -H "Authorization: Bearer <api_key>"

​
配信履歴を確認する

Webhook の配信試行ログを取得します。特定のイベントがサーバーに届いたか確認したり、配信失敗を診断するのに便利です。最新の試行から順に返され、各行に response_status、response_body、error が含まれます。 
curl "https://api.oneinbox.ai/v1/webhooks/<webhook_id>/deliveries?limit=50" \
  -H "Authorization: Bearer <api_key>"

​
API リファレンス

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