通話ごとの変数

デプロイ済みのプロンプト、ツール、設定を変更せずに、保存済みのエージェントを通話ごとにパーソナライズします。

保存済みエージェントのプロンプトにプレースホルダーを配置し、通話の開始時に variables オブジェクトを指定します。保存済みの設定とバージョン履歴は変更されません。ThunderPhone は、通話設定を音声ランタイムに送信する前にテキストをレンダリングします。

値が不要な場合は variables を省略し、null は送信しないでください（400 で拒否されます）。

プレースホルダーとデフォルト値

You are calling {{name|Friend}} about account {{account_id}}.
The available appointment is {{ appointment_slot }}.

名前では大文字と小文字が区別され、[A-Za-z_][A-Za-z0-9_]* に従います。名前の前後の空白は許可されます。| の後の空白はデフォルト値の一部として保持されます。{{name|Friend}} は、name が存在しないか null の場合に Friend を使用します。空文字列は明示的に指定された値として扱われます。デフォルト値のない欠落値は空文字列になり、その名前は unresolved_variables に表示されます。有効なプレースホルダーではない二重波括弧内のテキストは削除されます。指定した各値に含まれる二重波括弧内のテキストも個別に削除されます。値によって周囲のプロンプトテキストや別の値を削除することはできません。不一致の二重波括弧区切り文字も削除されます。プロンプト内の JSON 例では {{ を使用しないでください。値はプレーンテキストであり、コードとして評価されたり、テンプレートとして再帰的に展開されたりすることはありません。

変数は、確認プロンプト、発信ボイスメールメッセージ、および電話の通話時にそのフィールドが送信される場合の同意告知テキストにも使用できます。エージェントには個別の first_message フィールドはありません。開始時の指示はプロンプトに記述してください。既存のボイスメール用 {agent_name} および {org_name} プレースホルダーは引き続き利用できます。

値には文字列、数値、ブール値、または null を指定できます。ブール値は true および false としてレンダリングされます。改行（\n）、タブ（\t）、復帰（\r）を除く Unicode 制御（Cc）文字、すべての書式（Cf）文字、およびサロゲート（Cs）コードポイントは削除されます。\r\n は \n に正規化されます。各値はレンダリング時に 2,000 文字までに制限されます。指定した文字列も保存前にクリーンアップおよび切り詰められます。元のオブジェクトは 32 KB の UTF-8 JSON に収める必要があります。これより大きいオブジェクトは通話/セッションリクエストで 400 を受け取ります。一方、キャンペーンのインポートでは無効な行が個別に報告されます。配列およびネストしたオブジェクトは値として受け付けられません。一致しないメタデータキー（たとえば空白を含む CSV ヘッダー）は保持およびエコーされますが、プレースホルダーから参照することはできません。

値の取得元

発信 API

POST /v1/call で agent_id とともに variables を送信します。

{
  "from_number": "+15551234567",
  "to_number": "+14155550199",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  }
}

電話番号のデフォルト発信エージェントや、インラインの config.prompt でも使用できます。異なる変数で同じ冪等性キーを再利用することはできません。

キャンペーン CSV

電話番号以外の CSV 列は、すでに連絡先変数として保存されています。各発信で自動的に使用されます。プレースホルダーに一致させるには、name、account_id、appointment_slot などのヘッダーを使用します。既存の名前マッピングでは、名と姓の列を変数 name に結合できます。

動的設定Webhook

ブロッキング設定Webhookのパスでは、組織内の保存済みエージェントと通話ごとの値を返します。

{"agent_id": 12, "variables": {"name": "Ada", "account_id": "A-17"}}

レスポンスのキーはリクエストレベルの変数を上書きし、その他のリクエストキーは維持されます。レスポンス値を null にすると、プレースホルダーのデフォルトが選択されます。マージ後のオブジェクトも 32 KB に収める必要があります。保存済みエージェントのレスポンスで受け付けられるのは agent_id と variables のみです。プロンプトまたは設定を置き換える必要がある場合は、インライン設定を返します。prompt を含むレスポンスは常にインライン設定を使用します。そのレスポンス内の agent_id は、null または整数以外のメタデータを含めて無視されます。インラインプロンプトも通常の検証に合格する必要があります。インラインWebhookレスポンスには variables も含められます。保存済みエージェントのWebhookレスポンスでは、電話およびウィジェット通話の両方でエージェントにデプロイされた A/B 分割が使用され、変数はバリアント選択後にレンダリングされます。着信電話では、着信エージェントが割り当てられていない番号を使用し、その電話番号または組織のWebhookを設定します。ウィジェットキーでは mode="webhook" を使用します。エンドポイントシステムの受信通知では、ブロッキング設定レスポンスは提供されません。

ウィジェットおよび Realtime セッション API

POST /v1/widget/session は、トップレベルの variables オブジェクトを受け付けます。公開可能キーによって保存済みエージェントが選択されます。Webhookモードのキーはこれらの値を設定Webhookに転送し、前述のとおりレスポンスをマージします。ブラウザーから提供されるウィジェットまたはRealtimeの variables はクライアント制御です。前述の検証および文字列クリーンアップ後に web.incoming へそのまま転送され、完了Webhookと通話履歴にも返されます。信頼できるID情報または認可データとして扱わないでください。

POST /v1/realtime/sessions は、agent_id（またはインラインの config）とともに variables を受け付けます。これらはセッション作成 API のフィールドです。Realtime WebSocket ブリッジは variables オプションを転送しないため、セッション作成 API に直接指定します。ウィジェットクライアントは、送信するセッションペイロードに variables を含める必要があります。SDK による転送は、この API 変更の対象外です。Builder のマイク通話およびシミュレーションテスト通話ではデフォルトと未指定のプレースホルダーが解決されますが、通話ごとの変数入力はありません。

通話後に返される値

GET /v1/calls、GET /v1/calls/{call_id}、telephony.complete、および web.complete には、最終的にマージされた variables と unresolved_variables が含まれます。data.history を含むレガシー完了ペイロードにも、これらが含まれます。

{
  "variables": {"name": "Ada", "account_id": "A-17"},
  "unresolved_variables": ["appointment_slot"]
}

CRM またはタスクの識別子を変数オブジェクトに保存して、完了した通話をそのソースレコードに関連付けます。これらのフィールドは通話レコードとともに保持されます。通話履歴およびWebhookに保持して問題ない情報のみを送信してください。

既存プロンプトとの互換性

レンダリングは、既存の保存済みエージェントおよびA/Bバリアントのプロンプト、インラインのアウトバウンド設定とリアルタイム設定、設定Webhookから返されるプロンプトにも適用されます。不明な{{name}}プレースホルダーは、variablesが指定されていない場合でも空白テキストになります。ThunderPhoneでインベントリできない外部提供のインライン/Webhookプロンプトを含め、展開前に既存のプロンプトを確認してください。Builderのマイク通話とシミュレーション通話にも、同じデフォルト/空白の動作が適用されます。