每次通話變數

在不變更已部署提示詞、工具或設定的情況下，為每次通話個人化已儲存的智能體。

在已儲存智能體的提示中加入佔位符，然後在開始通話時提供 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 缺失或為 null 時，{{name|Friend}} 會使用 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 中，將 variables 與 agent_id 一併傳送：

{
  "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 回應會在電話及 Widget 通話中使用該智能體已部署的 A/B 分流；變數會在選取變體後呈現。對於來電電話通話，請使用未指派來電智能體的號碼，並設定其電話號碼或組織 Webhook；Widget 金鑰使用 mode="webhook"。端點系統的來電通知不會提供阻塞式設定回應。

POST /v1/widget/session 接受頂層 variables 物件。其可公開金鑰會選取已儲存的智能體。Webhook 模式的金鑰會將這些值轉送至設定 Webhook，並按上述方式合併回應。

由瀏覽器提供的 Widget／Realtime variables 由客戶端控制，會在完成上述驗證及字串清理後，於 web.incoming 中原樣轉送，並會回傳至完成 Webhook 及通話記錄。請勿將其視為可信賴的身分或授權資料。

POST /v1/realtime/sessions 接受與 agent_id（或內嵌 config）一併提供的 variables。這些是建立工作階段 API 的欄位。Realtime WebSocket 橋接不會轉送 variables 選項；請直接將其提供給建立工作階段 API。Widget 客戶端必須在已提交的工作階段負載中包含 variables；SDK 轉送並非此 API 變更的一部分。建構器咪高峰及模擬測試通話會解析預設值及缺少的預留位置，但不設每次通話變數輸入。

通話後傳回的值

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 傳回的提示詞。即使未有提供 variables，未知的 {{name}} 佔位符亦會顯示為空白文字。推出前請檢查現有提示詞，包括 ThunderPhone 無法清點、由外部提供的內嵌／webhook 提示詞。Builder 咪高峰及模擬通話同樣採用預設值／空白的行為。