動的変数 - Cartesia Docs

動的変数を使うと、マネージドエージェントが通話中に顧客の詳細情報やその他の値を利用できます。エージェントのテキストで変数を使うには、変数名を二重波かっこで囲んで記述します。たとえば、エージェントのウェルカムメッセージを次のように設定します：

Hi {{customer_name}}, how can I help you today?

customer_name として Jordan を渡すと、エージェントは「Hi Jordan, how can I help you today?」と話します。カスタム値は、通話リクエストまたは Webhook ツールのレスポンスから供給されます。{{system__caller_id}} などのシステム変数は、Cartesia が自動的に提供します。

値を挿入できる場所

場所	方法
指示プロンプト、ウェルカムメッセージ、keyterms、ツールとパラメータの説明、転送条件	テキスト内に `{{variable_name}}` と記述する
電話転送の宛先	電話番号の代わりに `{{variable_name}}` を使用する
Webhook のパス・クエリ・ボディパラメータとヘッダー	波かっこなしの変数名を使い、値のソースとして動的変数を設定する

名前は大文字と小文字を区別します。英字、数字、アンダースコアを使用できますが、数字で始めることはできません。

値の供給元

自分で渡す値

アウトバウンド通話リクエストで dynamic_variables を渡します。上記のウェルカムメッセージを設定したエージェントを、お客様自身の電話番号 ID と宛先とともに使用します：

POST /agents/calls

{
  "agent_id": "agent_Fo7pKNBUwLZxrTd6jvhpaE",
  "from_number_id": "ap_Q8PRh7lXyZsawXJmN2KcT5",
  "outbound_calls": [{
    "to_number": "+14155550123",
    "dynamic_variables": {
      "customer_name": "Jordan"
    }
  }]
}

バッチ通話では、各受信者の dynamic_variables に値を入れます。WebSocket セッションでは、お客様のサーバーから送信する session_create に含めます。値には、テキスト、数値、true/false の値を使用できます。

システム変数

Cartesia は通話コンテキストを自動的に提供します。たとえば、system__caller_id には発信者の電話番号が、system__time には現在の現地時刻が入ります：

The local time is {{system__time}}. Use it when discussing opening hours.

エージェントのタイムゾーンは、プレイグラウンドの Settings で選択します。デフォルトは UTC です。

利用可能なシステム変数

変数	値
`system__caller_id`	発信側の電話番号
`system__called_number`	着信側の電話番号
`system__call_direction`	電話通話の場合は `inbound` または `outbound`
`system__conversation_id`	Cartesia の通話 ID
`system__agent_id`	エージェント ID
`system__agent_version_id`	通話に使用されたエージェントのバージョン
`system__time`	エージェントのタイムゾーンでの現在時刻
`system__time_utc`	現在の UTC 時刻。例：`2026-09-07T15:30:00Z`
`system__timezone`	エージェントのタイムゾーン

電話番号と通話方向は、ブラウザでのプレビューを含め、利用できない場合は空になります。時刻の値は通話中に更新されます。

ツールのレスポンス

Webhook ツールは、レスポンスに含まれる値を保存して、通話の残りの間使用できます。代入（assignment） を追加して、どのレスポンスフィールドを保存し、どの変数を更新するかを選択します。注文検索が次を返すとします：

{
  "order": { "id": "A-1001", "status": "shipped" }
}

プレイグラウンドで Webhook ツールを開き、次の代入を追加します：

変数名	レスポンスパス
`order_id`	`order.id`
`order_status`	`order.status`

検索が成功すると、指示とツールの説明の中で {{order_status}} が shipped になります。他の Webhook ツールは、order_id をパラメータ値として使用できます。インバウンド通話では、「Thanks for calling. How can I help?」のように、発信者が誰か分かる前でも機能するウェルカムメッセージから始めてください。検索ツールで、電話番号のパラメータに system__caller_id を使用するよう設定し、返された顧客情報を保存する代入を追加します。いつ検索ツールを呼び出すかをエージェントに指示してください。これらの情報が利用可能になるのはツールの完了後であり、ウェルカムメッセージの前ではありません。

プレイグラウンドで試す

ウェルカムメッセージに Hi {{customer_name}}, how can I help? を追加します。{{ と }} の間に変数名を入力すると、エディターがカスタム変数とシステム変数を提案します。
Variables を開き、customer_name のサンプル値を Jordan に設定します。
Preview をクリックして、これらのサンプル値でテスト通話を開始します。

サンプルはテスト通話専用です。本番の通話でサンプルが使われることはありません。サンプルは config.dynamic_variable_placeholders からも保存できます。

重要な挙動

ウェルカムメッセージで使用するカスタム変数は、通話の開始前に利用可能である必要があります。
Webhook や電話転送が必要とする値が欠落しているか無効な場合、エージェントはツールエラーを受け取ります。リクエストや転送は行われません。
空のテキスト、0、false は、供給済みの値として扱われます。

代入が更新するのは現在の通話の値のみです。エージェントの保存済み設定を変更したり、次の通話に値を供給したりすることはありません。プレイグラウンドで Calls を開いて通話を選択すると、最終的な変数の値と代入を確認できます。これらは Get call からも取得できます。

​値の供給元

​自分で渡す値

​システム変数

​ツールのレスポンス

​プレイグラウンドで試す

​重要な挙動