WebSocket API - Cartesia Docs

WebSocket 経由でアプリケーションと音声エージェントの間で音声をストリーミングします。Web アプリ、モバイルアプリ、または独自のテレフォニープロバイダーをブリッジするのに使用できます。

クイックスタート

const ws = new WebSocket(
  `wss://api.cartesia.ai/agents/stream/${agentId}`,
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Cartesia-Version": "2025-04-16",
    },
  }
);

// Initialize the stream
ws.onopen = () => {
  ws.send(JSON.stringify({
    event: "start",
    config: { input_format: "pcm_44100" },
  }));
};

// Handle agent audio
ws.onmessage = (msg) => {
  const data = JSON.parse(msg.data);
  if (data.event === "media_output") {
    playAudio(atob(data.media.payload));
  }
  // Conversation events (turn_started, turn_output_text_delta, turn_ended)
  // also arrive here; see "Build a live transcript" below.
};

// Send user audio
function sendAudio(audioData) {
  ws.send(JSON.stringify({
    event: "media_input",
    stream_id: streamId,
    media: { payload: btoa(audioData) },
  }));
}

/access-token エンドポイントからアクセストークンを取得します。詳細はクライアントアプリの認証を参照してください。

接続

WebSocket エンドポイントに接続します：

wss://api.cartesia.ai/agents/stream/{agent_id}

ヘッダー：

ヘッダー	値
`Authorization`	`Bearer {token}`
`Cartesia-Version`	`2025-04-16`

プロトコル概要

WebSocket 接続は、制御イベントには JSON メッセージ、メディアには Base64 エンコードされた音声を使用します。新しいサーバーイベントの種類は今後追加される可能性があります。前方互換性を保つため、認識できないイベントはエラーとして扱わずに無視してください。セッションは 4 つのフェーズを経て進行します：

Start（開始）。 音声設定を含む start イベントを送信します。
Ready（準備完了）。 エージェントのパイプラインが準備できると、サーバーは ack で応答します。
Converse（会話）。 ユーザー音声を media_input としてストリーミングし、media_output からエージェント音声を再生します。並行して、サーバーは会話の進行を表す会話イベント（turn_started、turn_output_text_delta、turn_ended）をプッシュします。
End（終了）。 クライアントまたはサーバーのいずれからでも接続を閉じることができます。サーバーのクローズ理由は通話が終了した理由を伝えます（接続の管理を参照）。

通話後は、ack で受け取った call_id を使って通話 APIからセッションの完全なレコードを取得できます。

クライアントイベント

セッションの開始（`start`）

音声ストリームの構成を初期化します。

config はエージェントのデフォルトの入力音声設定を上書きします
stream_id は任意です。指定されない場合、サーバーが生成して ack イベントで返します

これは最初に送信するメッセージである必要があります。

{
  "event": "start",
  "stream_id": "unique_id",
  "config": {
    "input_format": "pcm_44100",
    "output_audio_delivery": "as_available",
    "voice_id": "a0e99841-438c-4a64-b679-ae501e7d6091"
  },
  "agent": {
    "introduction": "Hello, I'm an AI assistant",
    "system_prompt": "### Your Role \n You are a helpful assistant"
  },
  "metadata": {
    "to": "user@example.com",
    "from": "+1234567890"
  }
}

フィールド：

stream_id（任意）: ストリーム識別子。指定されない場合はサーバーが生成
config.input_format: クライアント音声入力の音声形式（mulaw_8000、pcm_16000、pcm_24000、pcm_44100）
config.output_audio_delivery（任意）: サーバーがエージェント音声を配信する方法。speaking_pace（デフォルト）は再生速度に合わせて音声をペーシングします。as_available はモデルが生成し次第送信するため、ローカルでバッファリングするクライアントは独自のクロックで再生でき、低遅延を実現できます。エージェントがバックグラウンド音声を使用する場合はサポートされません。
config.voice_id（任意）: エージェントのデフォルト TTS 音声を上書き
agent（任意）: API 経由で個別のエージェント通話を構成し、本番環境に公開せずに introduction やプロンプトの変更をプレビュー可能
metadata（任意）: カスタムメタデータオブジェクト。これらはエージェントコードに渡されますが、次のように利用できる特別なフィールドもあります：
- to（任意）: コールルーティング用の宛先識別子（デフォルトはエージェント ID）
- from（任意）: 通話の発信元識別子（デフォルトは「websocket」）

ユーザー音声のストリーミング（`media_input`）

クライアントからサーバーに送信される音声データです。payload の音声データは Base64 エンコードする必要があります。

{
  "event": "media_input",
  "stream_id": "unique_id",
  "media": {
    "payload": "base64_encoded_audio_data"
  }
}

フィールド：

stream_id: ack レスポンスから取得したストリームの一意の識別子
media.payload: start イベントで指定された形式の Base64 エンコードされた音声データ

DTMF トーンの送信（`dtmf`）

DTMF（デュアルトーン多重周波数）トーンを送信します。

{
  "event": "dtmf",
  "stream_id": "example_id",
  "dtmf": "1"
}

フィールド：

stream_id: ストリーム識別子
dtmf: DTMF 桁（0〜9、*、#）

カスタムメタデータの送信（`custom`）

エージェントにカスタムメタデータを送信します。

{
  "event": "custom",
  "stream_id": "example_id",
  "metadata": {
    "user_id": "user123",
    "session_info": "custom_data"
  }
}

フィールド：

stream_id: ストリーム識別子
metadata: カスタムデータのキーと値のペアを含むオブジェクト

サーバーイベント

セッションの準備完了（`ack`）

エージェントのパイプラインが音声を受信できる状態になると start に応答して送信されます。ストリーム構成を確認し、start イベントで指定されなかった場合はサーバー生成の stream_id を返します。

{
  "event": "ack",
  "stream_id": "example_id",
  "call_id": "agent_call_abc123",
  "config": {
    "input_format": "pcm_44100",
    "output_audio_delivery": "as_available",
    "voice_id": "a0e99841-438c-4a64-b679-ae501e7d6091"
  },
  "agent": {
    "system_prompt": "### Your Role \n You are a helpful assistant",
    "introduction": "Hello, I'm an AI assistant"
  }
}

フィールド：

call_id: このセッションに対して作成された通話レコードの識別子。通話 API と組み合わせて、通話終了後に録音とトランスクリプトを取得できます

エージェント音声の受信（`media_output`）

エージェントの発話です。payload は start イベントの config.input_format で指定された形式の Base64 エンコード音声です。

{
  "event": "media_output",
  "stream_id": "example_id",
  "media": {
    "payload": "base64_encoded_audio_data"
  }
}

会話イベント

会話そのものを表す 3 つのイベントがあります：turn_started、turn_output_text_delta、turn_ended。すべてのターンは、両ロールで共有される単一のカウンターから id を受け取ります。この id は 1 から始まり、通話全体を通じて厳密に単調増加するため、id だけでターンを一意に特定できます。 1 つのターンに関するイベントは、常に次の順序で到着します：turn_started、続いてゼロ個以上の turn_output_text_delta、最後に turn_ended。サーバーは会話の進行に合わせてこれらをプッシュし、音声の配信タイミングとは独立しています。これらのイベントを使ってトランスクリプトや発話中インジケーターを制御できます。コード例はライブトランスクリプトを構築するを参照してください。

ターンの開始時（`turn_started`）

ユーザーが話し始めた、またはエージェントが応答を開始したときに送信されます。

{
  "event": "turn_started",
  "stream_id": "example_id",
  "turn_started": {
    "id": 3,
    "role": "user",
    "start_timestamp": 12.48
  }
}

フィールド：

stream_id: ストリーム識別子
turn_started.id: ターンのインデックス。通話全体を通じて一意
turn_started.role: user または assistant
turn_started.start_timestamp: 通話開始からの経過秒数（おおよそクライアントが ack を受信した時点）

エージェントテキストのストリーミング（`turn_output_text_delta`）

エージェントが発話する各単語ごとに、発話とほぼ同時に送信されます。エージェント側のトランスクリプトを 1 単語ずつ描画するために使用します。

{
  "event": "turn_output_text_delta",
  "stream_id": "example_id",
  "turn_output_text_delta": {
    "id": 4,
    "role": "assistant",
    "text": " world"
  }
}

フィールド：

stream_id: ストリーム識別子
turn_output_text_delta.id: このテキストが属するターンの id と一致
turn_output_text_delta.role: 常に assistant
turn_output_text_delta.text: 追加する厳密な部分文字列。区切りのスペースも含まれるため、buffer[id] += text の形で連結してテキストを構築してください

これらのデルタはエージェントの発話のみをカバーします。ユーザーの発話は単語単位ではストリーミングされず、ユーザーのターンが終了したときに turn_ended イベントの確定テキストとして届きます。

ターンの終了時（`turn_ended`）

ターンが終了したときに送信されます。ターンの完全な確定テキストを含み、ターン終了後に保存・表示すべきバージョンです。

{
  "event": "turn_ended",
  "stream_id": "example_id",
  "turn_ended": {
    "id": 3,
    "role": "user",
    "text": "I'd like to check my order status.",
    "was_interrupted": false,
    "start_timestamp": 12.48,
    "end_timestamp": 15.02,
    "tool_calls": []
  }
}

フィールド：

stream_id: ストリーム識別子
turn_ended.id: 対応する turn_started イベントの id と一致
turn_ended.role: user または assistant
turn_ended.text: ターンの確定テキスト。ユーザーのターンでは書き起こされた発話、アシスタントのターンではエージェントが実際に発話したテキスト
turn_ended.was_interrupted: アシスタントのターンでは、ユーザーがターンを中断したときに true。ユーザーのターンでは、ターンの途中で通話が終了したときにのみ true
turn_ended.start_timestamp、turn_ended.end_timestamp: 通話開始からの経過秒数
turn_ended.tool_calls: ターン中に行われたツール呼び出し。各エントリは name、arguments、および任意で result と id を持ちます

エージェントがターンの途中で通話を切った場合、最後の turn_ended を送信せずに接続が閉じられます。接続が閉じたときは、開いているターンが終了したものとして扱ってください。

中断の処理（`clear`）

エージェントが現在の音声ストリームをクリア／中断したいことを示します。

{
  "event": "clear",
  "stream_id": "example_id"
}

通話の転送（`transfer_call`）

エージェントが通話を電話番号に転送したいことを示します。クライアントは自身のテレフォニー側で転送を開始する責任があります。

{
  "event": "transfer_call",
  "stream_id": "example_id",
  "transfer": {
    "target_phone_number": "+1234567890"
  }
}

フィールド：

stream_id: ストリーム識別子
transfer.target_phone_number: 通話を転送する E.164 形式の電話番号

ライブトランスクリプトを構築する

ライブトランスクリプトは、進行中の会話を UI に表示する機能で、エージェントの発話がライブキャプションのように 1 語ずつ現れます。

const turns = new Map();

ws.onmessage = (msg) => {
  const data = JSON.parse(msg.data);
  switch (data.event) {
    case "turn_started": {
      const { id, role } = data.turn_started;
      turns.set(id, { role, text: "", final: false });
      break;
    }
    case "turn_output_text_delta": {
      const { id, text } = data.turn_output_text_delta;
      const turn = turns.get(id);
      if (turn) turn.text += text; // deltas include separators
      break;
    }
    case "turn_ended": {
      const { id, role, text, was_interrupted } = data.turn_ended;
      turns.set(id, { role, text, was_interrupted, final: true });
      break;
    }
  }
  render([...turns.values()]);
};

ws.onclose = () => {
  // Close out any open turn.
  for (const turn of turns.values()) turn.final = true;
  render([...turns.values()]);
};

2 つのロールはテキストの届き方が異なるため、描画方法も分けます。ユーザーのターンでは、ターン開始時に発話中インジケーターを表示し、turn_ended が届いた時点でテキストを埋めます。エージェントのターンでは、各単語をデルタが届くたびに表示し、発話ペースに合わせて応答が積み上がるようにします。

接続の管理

無操作タイムアウト

サーバーは 180 秒 後にアイドル接続を閉じます。クライアントからのメッセージがあるたびにタイマーがリセットされます：

アプリケーションメッセージ（media_input、dtmf、custom イベント）
標準の WebSocket ping フレーム
その他の有効な WebSocket メッセージ

タイムアウトが発生すると、接続は次のように閉じられます：

コード： 1000（Normal Closure）
理由： "connection idle timeout"

Ping/Pong キープアライブ

無音期間中の無操作タイムアウトを防ぐため、定期的なキープアライブとして標準の WebSocket ping フレームを使用します：

# Client sends ping to reset inactivity timer
pong_waiter = await websocket.ping()
latency = await pong_waiter

// Requires the Node.js `ws` library — the browser WebSocket API does not expose ping()
setInterval(() => {
  if (websocket.readyState === WebSocket.OPEN) {
    websocket.ping();
  }
}, 60000); // Send ping every 60 seconds

サーバーは ping フレームに自動的に pong フレームで応答し、いずれかのメッセージを受信すると無操作タイマーをリセットします。

接続の終了

接続はクライアントまたはサーバーのどちらからでも WebSocket クローズフレームを使って閉じることができます。 クライアント開始のクローズ：

await websocket.close(code=1000, reason="session completed")

サーバー開始のクローズ： エージェントが通話を終了すると、サーバーは次のように接続を閉じます：

コード： 1000（Normal Closure）
理由： "call ended by agent"、または追加のコンテキストが利用可能な場合は "call ended by agent, reason: {specific_reason}"

ベストプラクティス

最初に start を送信 — start より前に他のイベントが送信されると接続は閉じられます。
適切な音声形式を選択 — ソースに合わせて形式を選択してください：テレフォニーには mulaw_8000、Web クライアントには pcm_44100。
クローズを適切に処理 — デバッグやリカバリのため、常にクローズコードと理由をキャプチャしてください。
接続を維持 — 180 秒の無操作タイムアウトを回避するため、60〜90 秒ごとに WebSocket ping フレームを送信してください。
ストリーム ID を管理 — システム全体のオブザーバビリティ（可観測性）を高めるため、独自の stream_id 値を指定してください。
アイドルタイムアウトから復旧 — 1000 / connection idle timeout の場合、再接続して start イベントを再送してください。

​クイックスタート

​接続

​プロトコル概要

​クライアントイベント

​セッションの開始（start）

​ユーザー音声のストリーミング（media_input）

​DTMF トーンの送信（dtmf）

​カスタムメタデータの送信（custom）

​サーバーイベント

​セッションの準備完了（ack）

​エージェント音声の受信（media_output）

​会話イベント

​ターンの開始時（turn_started）

​エージェントテキストのストリーミング（turn_output_text_delta）

​ターンの終了時（turn_ended）

​中断の処理（clear）

​通話の転送（transfer_call）

​ライブトランスクリプトを構築する

​接続の管理

​無操作タイムアウト

​Ping/Pong キープアライブ

​接続の終了

​ベストプラクティス

クイックスタート

接続

プロトコル概要

クライアントイベント

セッションの開始（`start`）

ユーザー音声のストリーミング（`media_input`）

DTMF トーンの送信（`dtmf`）

カスタムメタデータの送信（`custom`）

サーバーイベント

セッションの準備完了（`ack`）

エージェント音声の受信（`media_output`）

会話イベント

ターンの開始時（`turn_started`）

エージェントテキストのストリーミング（`turn_output_text_delta`）

ターンの終了時（`turn_ended`）

中断の処理（`clear`）

通話の転送（`transfer_call`）

ライブトランスクリプトを構築する

接続の管理

無操作タイムアウト

Ping/Pong キープアライブ

接続の終了

ベストプラクティス