> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneinbox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 通話

> アウトバウンド発信、インバウンド着信、結果の取得、通話レコードの管理を行います。OneInbox はすべての通話後に自動的にコール結果を分類します。

## アウトバウンド発信

登録済みの `from_number` と発信先の `to_number` を渡します。`variables` を使うと、通話ごとのコンテキスト（顧客名や注文 ID など）をエージェントの最初のメッセージとシステムプロンプトに注入できます。

```bash theme={null}
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",
    "variables": { "customer_name": "Sama", "order_id": "ORD-001" },
    "webhook_url": "https://your-server.com/per-call-webhook",
    "out_sms": false
  }'
```

| オプションフィールド    | デフォルト   | 役割                                           |
| ------------- | ------- | -------------------------------------------- |
| `variables`   | `{}`    | 通話時にエージェントのシステムプロンプトと最初のメッセージに注入するキーと値のペア    |
| `webhook_url` | —       | 通話ごとの Webhook URL — この通話のみグローバル Webhook を上書き |
| `out_sms`     | `false` | 通話終了後に `to_number` へ SMS を送信する               |
| `schedule_at` | —       | 将来の時刻に通話をスケジュールする ISO 8601 タイムスタンプ           |

```json theme={null}
{
  "id": "call_abc123",
  "status": "initiated",
  "to_number": "+919876543210",
  "from_number": "+15739693824"
}
```

通話は以下のステータスを経由します：

| ステータス         | 意味                   |
| ------------- | -------------------- |
| `initiated`   | 通話が作成され、プロバイダー経由で接続中 |
| `in_progress` | 通話が接続され、エージェントが会話中   |
| `completed`   | 通話が正常に終了             |
| `failed`      | 通話の接続に失敗             |

***

## インバウンド着信

登録済みの番号に電話がかかってくると、OneInbox が自動的にエージェントへルーティングします — 追加の API 呼び出しは不要です。着信の通話レコードはアウトバウンドと同じ形式で作成され、`status`、`outcome`、`messages`、`recording_url` などのフィールドも同様に取得できます。

番号でインバウンドを有効にするには、番号の登録・購入時に `inbound_routing` を設定します：

```json theme={null}
"inbound_routing": {
  "agent_id": "<routing_agent_id>",
  "fallback": { "agent_id": "<fallback_agent_id>" },
  "voicemail_message": "ただいま対応できません。メッセージをお残しください。"
}
```

既存の番号にルーティングを追加・更新する場合：

```bash theme={null}
curl -X PATCH https://api-tokyo.oneinbox.ai/v1/phone-numbers/<phone_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "inbound_routing": {
      "agent_id": "<routing_agent_id>",
      "voicemail_message": "更新後のボイスメールメッセージ。"
    }
  }'
```

→ [電話番号](/jp/guides/phone-calls) — 検索・購入・持ち込み番号のセットアップ

***

## 通話を停止する

セッションを終了するために停止リクエストを送信します。エージェントがすでに `end_call` ツールで通話を終了している場合、これは無効な操作となります。

```bash theme={null}
curl -X POST https://api-tokyo.oneinbox.ai/v1/calls/<call_id>/stop \
  -H "Authorization: Bearer <api_key>"
```

***

## 結果を読む

通話終了後、完全なレコードを取得してトランスクリプト、結果、サマリーを確認します。停止後 2〜3 秒待ってください — トランスクリプトと分析は非同期で書き込まれます。

```bash theme={null}
curl https://api-tokyo.oneinbox.ai/v1/calls/<call_id> \
  -H "Authorization: Bearer <api_key>"
```

```json theme={null}
{
  "id": "call_abc123",
  "status": "completed",
  "duration_seconds": 87,
  "messages": [
    { "role": "agent", "content": "Hi Sama! This is Aria from Acme." },
    { "role": "user",  "content": "Oh hi, yes I've been expecting your call." }
  ],
  "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."
  },
  "recording_url": "https://storage.oneinbox.ai/recordings/call_abc123.mp3",
  "latency": {
    "llm_ttft": { "avg_ms": 857, "p50_ms": 820, "min_ms": 710, "max_ms": 1050, "samples": 4 },
    "tts_ttfb": { "avg_ms": 312, "p50_ms": 290, "min_ms": 240, "max_ms": 410, "samples": 4 },
    "eou_delay": { "avg_ms": 180, "p50_ms": 175, "min_ms": 140, "max_ms": 230, "samples": 4 }
  },
  "credits_used": 1.45,
  "cost_cents": 8.7
}
```

`messages` と `analysis` は通話終了後にのみ入力されます。まず停止し、2〜3 秒待ってから取得してください。

| フィールド               | 利用可能になるタイミング | 意味                                                                     |
| ------------------- | ------------ | ---------------------------------------------------------------------- |
| `latency.llm_ttft`  | 通話終了後        | LLM からの最初のトークンまでの時間 — ターンごとに avg/p50/min/max                           |
| `latency.tts_ttfb`  | 通話終了後        | TTS からの最初のバイトまでの時間 — ターンごと                                             |
| `latency.eou_delay` | 通話終了後        | 発話終了検出の遅延 — エージェントが応答を開始するまでの時間                                        |
| `credits_used`      | 通話終了後        | OneInbox 課金単位 — `duration_seconds ÷ 60`（1 クレジット = 1 分）                 |
| `cost_cents`        | キャリアによる非同期確定 | 実際のキャリアコスト（Twilio/Telnyx）。ハングアップ直後は `null` の場合あり — キャリア確定後に補完          |
| `recording_url`     | 通話終了後（有効な場合） | 事前署名付き S3 URL、4 時間有効。GET するたびに新しい URL が返るため、アクティブなインテグレーションでは期限切れにならない |

***

## 通話を一覧表示する

アカウントのすべての通話を取得します。デフォルトは新しい順です。

```bash theme={null}
curl https://api-tokyo.oneinbox.ai/v1/calls \
  -H "Authorization: Bearer <api_key>"
```

***

## 通話一覧（カーソルページネーション）

大量の結果セットに対して、カーソルページネーションを使用すると新しい通話が追加されてもレコードの重複やスキップを防げます。各レスポンスに `cursor` トークンが含まれるので、次のリクエストで渡してください。

```bash theme={null}
# 最初のページ
curl "https://api-tokyo.oneinbox.ai/v1/calls/cursor?limit=20" \
  -H "Authorization: Bearer <api_key>"

# 次のページ — 前のレスポンスの cursor を渡す
curl "https://api-tokyo.oneinbox.ai/v1/calls/cursor?cursor=<cursor>&limit=20" \
  -H "Authorization: Bearer <api_key>"
```

`cursor` が `null` の場合は最終ページです。

***

## 通話を削除する

通話レコードを完全に削除します。

```bash theme={null}
curl -X DELETE https://api-tokyo.oneinbox.ai/v1/calls/<call_id> \
  -H "Authorization: Bearer <api_key>"
```

***

## 通話結果を手動で設定する

通話終了後、AI が割り当てた結果を上書きできます — CRM や人間のレビュアーが異なる分類をした場合に便利です。

```bash theme={null}
curl -X PATCH https://api-tokyo.oneinbox.ai/v1/calls/<call_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "outcome": "interested" }'
```

更新された `outcome` の値は、`GET /v1/calls/<call_id>` とその通話の Webhook ペイロードに即座に反映されます。

***

## コール結果とは？

コール結果とは、完了した通話に割り当てられるラベルで、その結果を要約したものです。通話レコードの**トップレベル** `outcome` フィールドで、通話終了後に自動的に設定されます。`analysis` は別オブジェクトで、AI 生成の `summary` のみを保持します — `outcome` は含まれません。`outcome` は手動で設定・上書きすることも可能で、ワークスペース独自のカスタム結果ラベルを作成することもできます。

***

## 組み込みの結果ラベル

OneInboxにはすべてのアカウントで利用可能なプラットフォームレベルの結果が用意されています。`GET /v1/workspace/call-outcomes` は snake\_case の識別子を返し、通話レコードの `outcome` フィールドには人が読みやすい Title Case 形式が格納されます：

| 識別子（`call-outcomes` カタログ） | `call.outcome` に格納される形式 | 意味                       |
| ------------------------- | ----------------------- | ------------------------ |
| `appointment_booked`      | `Appointment Booked`    | 会議やデモが予定された              |
| `callback_requested`      | `Callback Requested`    | 発信者が後でかけ直すよう依頼した         |
| `completed`               | `Completed`             | 他のどの結果にも当てはまらず通話が終了した    |
| `do_not_call`             | `Do Not Call`           | 発信者が今後の連絡を拒否した           |
| `failed`                  | `Failed`                | 通話が正常に接続しなかった            |
| `interested`              | `Interested`            | 発信者は関心を示したが確約しなかった       |
| `no_answer`               | `No Answer`             | 呼び出したが応答がなかった            |
| `not_connected`           | `Not Connected`         | 会話が成立しなかった（話中、即切断）       |
| `not_interested`          | `Not Interested`        | 発信者が明示的に断った              |
| `other`                   | `Other`                 | 他のどのラベルにも当てはまらない         |
| `spam`                    | `Spam`                  | スパム・迷惑電話と判定された           |
| `voicemail`               | `Voicemail`             | 留守番電話が検出された              |
| `wrong_number`            | `Wrong Number`          | 間違った相手・番号に繋がった           |
| —                         | `null`                  | 結果が分類されなかった — 通話が短すぎるか曖昧 |

***

## 自動分類の仕組み

すべての通話終了後、OneInboxは文字起こしを読み取り、自動的に結果を割り当てます。設定は不要です。

いくつかの注意点：

* **分類は通話後に行われます。** アクティブな通話中は `outcome` は `null` です。通話終了後にレコードを取得してください。
* **`ai_summary` が判断理由を説明します。** 結果が正しくないと思われる場合は、サマリーを読んでモデルが会話の何を見たかを確認してください。
* **カスタム結果も使用されます。** カスタム結果ラベルを作成している場合、エージェントは通話分類時に組み込みセットに加えてそれらも使用します。

***

## カスタム結果ラベル

ワークスペース独自のカスタム結果ラベルを作成できます。エージェントは通話分類時に組み込みラベルと合わせてこれらを使用します。例えば「ホットリード」をカスタム結果として追加すると、AIはその説明に合致する通話に自動的に割り当て始めます。

### コール結果の一覧取得

プラットフォームレベルの組み込みラベル（常に利用可能）と、ワークスペースで作成したカスタムラベルの両方を返します。

```bash theme={null}
curl https://api-tokyo.oneinbox.ai/v1/workspace/call-outcomes \
  -H "Authorization: Bearer <api_key>"
```

```json theme={null}
{
  "builtin": [
    "appointment_booked", "callback_requested", "completed", "do_not_call",
    "failed", "interested", "no_answer", "not_connected", "not_interested",
    "other", "spam", "voicemail", "wrong_number"
  ],
  "items": [
    {
      "id": "co_abc123",
      "label": "Hot Lead",
      "description": "Expressed strong interest and asked specific product questions",
      "is_active": true
    }
  ],
  "total": 1
}
```

### カスタム結果の作成

ワークスペースに新しい結果ラベルを追加します。大文字・小文字は任意です（例：`"ホットリード"` や `"demo_scheduled"`）。作成後、エージェントは今後の通話分類時に自動的にそれを使用します。

```bash theme={null}
curl -X POST https://api-tokyo.oneinbox.ai/v1/workspace/call-outcomes \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Hot Lead",
    "description": "Qualified lead with confirmed budget and decision timeline"
  }'
```

```json theme={null}
{
  "id": "co_abc123",
  "label": "Hot Lead",
  "description": "Qualified lead with confirmed budget and decision timeline",
  "is_active": true
}
```

| フィールド         | 役割                                          |
| ------------- | ------------------------------------------- |
| `label`       | 結果名。大文字・小文字はそのまま保存・表示されます                   |
| `description` | 任意。AIにこの結果が適用されるタイミングを説明します。詳しいほど分類精度が上がります |

### カスタム結果の更新

ラベルの名前変更や無効化ができます。無効化（`is_active: false`）すると、今後の自動分類からは除外されますが、過去の通話レコードには保持されます。データは失われません。

```bash theme={null}
curl -X PATCH https://api-tokyo.oneinbox.ai/v1/workspace/call-outcomes/<outcome_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Qualified Lead",
    "is_active": true
  }'
```

| フィールド       | 役割                                       |
| ----------- | ---------------------------------------- |
| `label`     | 新しいラベル名 — 今後の通話レコードに表示される名前が更新されます       |
| `is_active` | `false` = 過去データを保持したまま、新しい分類からこの結果を除外します |

***

## Webhookで自動通知を受け取る

ポーリングの代わりに、通話終了直後に完全な通話レコードを受け取るWebhookを設定します：

```bash theme={null}
curl -X POST https://api-tokyo.oneinbox.ai/v1/webhooks \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Call completed",
    "url": "https://your-server.com/webhooks/oneinbox",
    "events": ["call.ended"]
  }'
```

→ [Webhookガイド](/jp/guides/webhooks)

***

## APIリファレンス

[アウトバウンド通話を作成](/api-reference/calls/create-outbound-call) · [通話を停止](/api-reference/calls/stop-call) · [通話を取得](/api-reference/calls/get-call) · [通話を更新](/api-reference/calls/update-call) · [通話一覧](/api-reference/calls/list-calls) · [通話を削除](/api-reference/calls/delete-call) · [コール結果一覧](/api-reference/workspace/list-call-outcomes) · [コール結果を作成](/api-reference/workspace/create-call-outcome) · [コール結果を更新](/api-reference/workspace/update-call-outcome)