每通通話變數

為每通通話個人化已儲存的智慧體，無需變更其已部署的提示詞、工具或設定。

在已儲存的智慧體提示詞中加入預留位置，然後在開始通話時提供 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 回應會在電話和小工具通話中使用該智慧體已部署的 A/B 分流；變數會在選取變體後呈現。在撥入電話時，請使用未指派撥入智慧體的號碼，並設定其電話號碼或組織 webhook；小工具金鑰使用 mode="webhook"。端點系統傳入通知不會提供阻塞式設定回應。

小工具與 Realtime 工作階段 API

POST /v1/widget/session 接受頂層的 variables 物件。其可發布金鑰會選取已儲存的智慧體。Webhook 模式金鑰會將這些值轉送至設定 webhook，並依上述方式合併回應。瀏覽器提供的小工具／realtime variables 由用戶端控制，會在完成上述驗證與字串清理後，原樣轉送至 web.incoming，並回傳至完成 webhook 和通話紀錄。請勿將其視為可信任的身分識別或授權資料。

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 或工作識別碼儲存在 variables 物件中，以便將已完成的通話連結回其來源紀錄。這些欄位會與通話紀錄一併保留；請只傳送適合保留於通話紀錄和 webhook 中的資訊。

與既有提示詞的相容性

渲染同樣適用於既有已儲存的智慧體提示詞與 A/B 變體提示詞、內嵌的外撥與即時設定，以及由設定 Webhook 傳回的提示詞。未知的 {{name}} 預留位置會顯示為空白文字，即使未提供 variables 也是如此。在正式推出前，請檢查既有提示詞，包括 ThunderPhone 無法盤點的外部提供內嵌／Webhook 提示詞。Builder 麥克風與模擬通話也會套用相同的預設／空白行為。