オブザーバビリティ

すべてのデプロイメントと通話を監視します。

通話オブザーバビリティのデモ

デプロイメント

各デプロイメントには一意の ID が生成されます。ログはコンソールで確認できます。

コールログ

通話をクリックして、推論コードが生成したログ出力を確認できます。

コールログ

トランスクリプト

各通話には、書き起こされた音声と生成されたテキストが独立して分かれたトランスクリプトがあります。これらのトランスクリプトを API または CLI でエクスポートすると、より詳細なターン単位のタイムスタンプも含まれます。

ロギング可能なイベント

ツール呼び出しに紐付けずにイベントを記録します。

SDK

SDK では、エージェントまたはツールから LogMessage イベントを yield することでカスタムイベントを記録できます：

from line.events import LogMessage

@loopback_tool
async def process_order(ctx, order_id: Annotated[str, "Order ID"]):
    """Process a customer order."""
    result = await api.process_order(order_id)

    # Log a custom event
    yield LogMessage(
        name="order_processed",
        level="info",
        message=f"Processed order {order_id}",
        metadata={"status": result.status, "order_id": order_id}
    )

    return f"Order {order_id} processed: {result.status}"

yield されたイベントは自動的にプラットフォームへ送信されます。

Websocket

SDK を使わずに素の WebSocket を使用している場合、ロギングイベントは次のようになります：

{
  "type": "log_event",
  "event": "event_name",
  "metadata": {
    "key": "value"
  }
}

Playground

プレイグラウンドでは通話の Transcript タブからこれらのイベントを確認できます。

ロギング可能なメトリクス

ワークフロー内の任意のポイントでメトリクスを記録します。

SDK

SDK では、LogMetric イベントをブロードキャストすることでメトリクスを記録できます。これを示すフォーム入力テンプレートからの抜粋：

# Record the answer in form manager
success = self.form_manager.record_answer(answer)

if success:
  # Log metric for the answered question
  if current_question:
    metric_name = current_question["id"]
    yield LogMetric(name=metric_name, value=answer)
    logger.info(f"📊 Logged metric: {metric_name}={answer}")

ユーザーブリッジはデフォルトで LogMetric イベントを購読しており、LogMetric がブロードキャストされたことを検出すると、デフォルトでそれを WebSocket 経由でログとして送信します。

Websocket

SDK を使わずに素の WebSocket を使用している場合、メトリクスのロギングは次のようになります：

{
  "type": "log_metric",
  "name": "metric_name",
  "value": "metric_value"
}

Playground

プレイグラウンドでは通話の Transcript タブからこれらのイベントを確認できます。

通話の録音

デフォルトでは、Cartesia はすべてのエージェント通話の音声とトランスクリプトを録音し、通話終了後に確認できるようにします。録音はプレイグラウンドからダウンロードできます。プログラムからは GET /agents/calls/{call_id}/audio で WAV ファイルとして取得できます。トランスクリプトは GET /agents/calls/{call_id} のレスポンスに含まれます。

録音と保持の制御

通話中に録音を停止する、通話単位や通話中に切り替えるためのトグルはありません。通話相手が録音への同意を撤回した場合は、以下のいずれかの対応を行ってください。

通話を終了する。 エージェント側で切断するか、通話相手に切断してもらいます。通話終了後は追加の音声は取得されません。
通話終了後に録音を削除する。 通話が completed または failed になったら、DELETE /agents/calls/{call_id} を呼び出します。Cartesia はトランスクリプト、音声録音、ログを削除し、通話レコードに redacted_at を設定し、以降の API レスポンスから削除されたフィールドを省略します。削除は取り消せません。進行中の通話は先に POST /agents/calls/{call_id}/cancel でキャンセルしてください。
そもそも通話コンテンツを保持しない。 Enterprise のお客様は組織単位で Zero Data Retention を有効化できます。ZDR が有効な場合、通話レコードの zdr_enabled は true となり、Cartesia はトランスクリプト、音声録音、ログを一切保持しません。ZDR は組織全体の設定で、通話単位や通話中の切り替えはできません。

現地の録音、同意、告知に関する要件を満たす責任はお客様にあります。詳細は Cartesia の Acceptable Use Policy を参照してください。

Webhook

Cartesia は通話のライフサイクル全体を通じて、お客様の HTTPS エンドポイントに Webhook イベントを送信します。POST + application/json を公開し、x-webhook-secret ヘッダーが保存済みのシークレットと一致することを検証してください。

Webhook シークレットの検証

Python
TypeScript

if request.headers.get("x-webhook-secret") != os.environ["LINE_WEBHOOK_SECRET"]:
    return jsonify({"error": "unauthorized"}), 401

if (req.headers["x-webhook-secret"] !== process.env.LINE_WEBHOOK_SECRET)
  return res.status(401).json({ error: "unauthorized" });

イベントタイプ

イベント	発生タイミング	型付きフィールド
`call_started`	通話セッションが開始される	`call`
`call_completed`	通話が正常に終了する	`call`
`call_failed`	通話がエラーで終了する	`call`
`call_turn`	各会話ターン	`turn`
`post_call_analysis`	非同期分析の完了後	`analysis`

エンベロープフィールド

すべての Webhook イベントには、以下のトップレベルフィールドが含まれます：

フィールド	説明
`type`	イベントタイプ（上記の表を参照）。
`call_id`	通話の識別子。
`agent_id`	通話を処理したエージェント。
`webhook_id`	Webhook 設定 ID。
`timestamp`	RFC 3339 形式のイベント時刻。

`call`

call_started、call_completed、call_failed イベントに含まれます。GET /agents/calls/{call_id} のレスポンスと一致します。一部のイベント（例：call_started）では、まだ有効な値を持たない end_time などのフィールドが省略される場合があります。

フィールド	説明
`id`	通話の識別子。
`agent_id` / `agent_name`	エージェントの詳細。
`status`	`started`、`completed`、または `failed`。
`start_time` / `end_time`	RFC 3339 形式のタイムスタンプ。
`end_reason`	通話終了の理由（例：`client_hangup`、`agent_hangup`、`inactivity`）。すべての値については EndReason を参照。
`transcript`	ターンの配列（下記の `turn` を参照）。
`telephony_params`	`from`、`to`、`direction`、`call_sid`、`connection_type`。
`telephony_account_type`	`cartesia`、`twilio`、または `sip_trunk`。
`deployment_id` / `deployment_version_id`	通話を処理したデプロイメント（該当する場合）。
`deployment_region`	`US`、`EU`、または `APAC`。
`error_message`	エラーの詳細（失敗した通話のみ）。
`metadata`	通話開始時に渡されたユーザー指定のメタデータ。
`summary`	通話の要約（イベント発生時に利用可能な場合）。

`turn`

call_turn イベントに含まれます。エージェントまたはユーザーの発話ごとに 1 ターン。

フィールド	説明
`role`	`assistant` または `user`。
`text`	ターンのテキスト。
`start_timestamp` / `end_timestamp`	通話開始からの秒数。
`stt_ttfb`	ユーザー音声認識（STT）のタイム・トゥ・ファースト・バイト（秒）、利用可能な場合。
`tts_ttfb`	エージェント TTS のタイム・トゥ・ファースト・バイト（秒）、利用可能な場合。
`tool_calls`	このターン中に行われたツール呼び出し、利用可能な場合。

`analysis`

post_call_analysis イベントに含まれます。非同期分析の完了後に送信されます（現時点では要約の生成。今後、評価とメトリクスがここに追加される予定です）。

フィールド	説明
`summary`	1〜2 文の通話要約。

例: `call_completed`

{
  "type": "call_completed",
  "call_id": "ac_sid_gqkgRWUz2u64qFUjA1mZyr",
  "agent_id": "agent_rwh4HGMgyhK7rM5ucVqbiC",
  "webhook_id": "agent_webhook_P3MgdLf1cpaucZJ7xWehCC",
  "end_reason": "client_hangup",
  "timestamp": "2026-04-16T01:08:50.061907836Z",
  "call": {
    "id": "ac_sid_gqkgRWUz2u64qFUjA1mZyr",
    "agent_id": "agent_rwh4HGMgyhK7rM5ucVqbiC",
    "agent_name": "My Agent",
    "status": "completed",
    "start_time": "2026-04-16T01:08:37.413659Z",
    "end_time": "2026-04-16T01:08:50.036327Z",
    "end_reason": "client_hangup",
    "telephony_params": {
      "from": "websocket",
      "to": "agent_rwh4HGMgyhK7rM5ucVqbiC",
      "connection_type": "websocket"
    },
    "transcript": [
      {
        "role": "assistant",
        "text": "Hi there! How can I help you today?",
        "start_timestamp": 0.41,
        "end_timestamp": 3.2,
        "tts_ttfb": 0.065
      },
      {
        "role": "user",
        "text": "I want to schedule an appointment.",
        "start_timestamp": 3.5,
        "end_timestamp": 5.8
      }
    ]
  }
}

例: `post_call_analysis`

{
  "type": "post_call_analysis",
  "call_id": "ac_sid_gqkgRWUz2u64qFUjA1mZyr",
  "agent_id": "agent_rwh4HGMgyhK7rM5ucVqbiC",
  "webhook_id": "agent_webhook_P3MgdLf1cpaucZJ7xWehCC",
  "timestamp": "2026-04-16T01:08:50.955058787Z",
  "analysis": {
    "summary": "The caller requested to schedule an appointment. The agent confirmed availability and booked a slot."
  }
}

エンドポイントのテスト

curl -sS -X POST "https://your-server.example/webhooks/cartesia" \
  -H "Content-Type: application/json" \
  -H "x-webhook-secret: YOUR_WEBHOOK_SECRET" \
  -d '{
    "type": "call_completed",
    "call_id": "ac_test_123",
    "agent_id": "agent_demo",
    "webhook_id": "agent_webhook_test",
    "timestamp": "2026-01-01T00:00:00.000000000Z",
    "call": {
      "id": "ac_test_123",
      "agent_id": "agent_demo",
      "agent_name": "Test Agent",
      "status": "completed",
      "end_reason": "client_hangup",
      "transcript": []
    }
  }'

後方互換性のため：

call_completed および call_failed イベントには、トップレベルの body（トランスクリプト配列）とトップレベルの end_reason も含まれます。代わりに call.transcript と call.end_reason を使用してください。
call_turn イベントには、生のターンペイロードを含むトップレベルの body も含まれます。代わりに turn を使用してください。

これらの非推奨フィールドは将来のリリースで削除されます。

​デプロイメント

​コールログ

​トランスクリプト

​ロギング可能なイベント

​SDK

​Websocket

​Playground

​ロギング可能なメトリクス

​SDK

​Websocket

​Playground

​通話の録音

​録音と保持の制御

​Webhook

​Webhook シークレットの検証

​イベントタイプ

​エンベロープフィールド

​call

​turn

​analysis

​例: call_completed

​例: post_call_analysis

​エンドポイントのテスト

デプロイメント

コールログ

トランスクリプト

ロギング可能なイベント

SDK

Websocket

Playground

ロギング可能なメトリクス

SDK

Websocket

Playground

通話の録音

録音と保持の制御

Webhook

Webhook シークレットの検証

イベントタイプ

エンベロープフィールド

`call`

`turn`

`analysis`

例: `call_completed`

例: `post_call_analysis`

エンドポイントのテスト