Open in
每通電話的變數與情境
為每通電話提供專屬詳細資訊,可作為提示詞的具名變數或自由格式簡述,無須變更智慧體。
每通電話都可帶入兩種類型的單次通話輸入。你可以擇一使用,也可以同時使用:
variables:填入提示詞中{{placeholders}}的具名值。適用於提示詞以名稱參照的欄位,例如來電者姓名、帳號或預約時段。context:新增在提示詞之後的自由格式文字。適用於不適合使用範本的簡述,例如本次通話的任務說明或先前蒐集的備註。
兩者皆可搭配已儲存的智慧體與內嵌設定,並適用於以下所述的所有發起通話方式。兩者都不會變更已儲存的智慧體、其版本紀錄或其他設定。
{
"agent_id": 12,
"variables": {"name": "Ada", "appointment_slot": "Tuesday at 10 AM"},
"context": "Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number."
}變數
在已儲存的智慧體提示詞中加入預留位置,然後在開始通話時提供 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)字元、除了零寬不連字元和連字元(U+200C、U+200D,這些字元用於拼寫印度語系及阿拉伯字母語言中的詞語)之外的格式(Cf)字元,以及代理(Cs)碼位都會被移除;\r\n
會正規化為 \n。每個值在呈現時
最多可包含 2,000 個字元。提供的字串也會在儲存前清理並截斷。原始物件必須符合 32 KB 的 UTF-8 JSON;較大的物件在通話/工作階段請求中會收到 400,而行銷活動匯入會逐一回報無效資料列。不接受陣列和巢狀物件作為值。不符規則的中繼資料鍵(例如含有空格的 CSV 標頭)會保留並回傳,但無法由預留位置參照。
情境
context 是最多 20,000 個字元的字串。ThunderPhone 會在提示詞的變數填入後,將其作為分隔區塊加在提示詞之後:
<your prompt, with its variables filled in>
Details for this call:
<call_context>
Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number.
</call_context>智慧體會連同其指示一併讀取,因此請以你在通話前向同事說明的方式撰寫。情境不是範本:
其中的 {{name}} 會維持原樣。如果文字需要某個值,請在傳送前自行填入該值。
null、空字串或僅含空白字元表示沒有情境資訊。- 非字串值,或超過 20,000 個字元的值,會在通話和工作階段請求中以
400拒絕;若來自設定 Webhook,則會像無效的variables一樣使交換失敗(見下文)。 - 會修剪開頭與結尾的空白字元,並移除與變數值相同的控制字元和格式字元。
- 情境資訊是通話提示的一部分,因此會計入通話的提示大小。
在 steps 智慧體中,情境會接在通話中每個智慧體的提示詞後,而不是接在各步驟的指示後。
值的來源
外撥 API
在 POST /v1/call 上傳送 variables 和 context:
{
"from_number": "+15551234567",
"to_number": "+14155552671",
"agent_id": 12,
"variables": {
"name": "Ada",
"account_id": "A-17",
"appointment_slot": "Tuesday at 10 AM"
},
"context": "Ada asked to be called back about the late fee on her March invoice."
}兩者也可搭配電話號碼的預設撥出語音智慧體或內嵌的
config.prompt 使用。使用內嵌設定時,context 也可放在 config
內,這與設定 webhook 回傳的欄位相同;如果兩者都傳送,文字必須完全相同。冪等性金鑰不可重複用於不同的變數或不同的內容。
行銷活動 CSV
非電話 CSV 欄位已儲存為聯絡人變數。每次撥號現在都會自動使用這些變數。請使用 name、account_id 和 appointment_slot 等標題來對應你的預留位置。現有的姓名對應可將名字與姓氏欄位合併為 name 變數。行銷活動聯絡人沒有每位聯絡人的情境資訊。
動態設定 webhook
在封鎖式設定 webhook 路徑上,傳回你組織中已儲存的智慧體,以及任何每通電話的值。對於 Full duplex 智慧體,即使通話以另一種支援的語言開始,通話仍會保留該智慧體的語音: 該通話不會套用各語言的語音對應或原生語音切換。
{
"agent_id": 12,
"variables": {"name": "Ada", "account_id": "A-17"},
"context": "[REDACTED_LITERAL]"
}{
"agent_id": 12,
"variables": {"name": "Ada", "account_id": "A-17"},
"context": "Ada called yesterday about a leak in unit 4B; a plumber is booked for Friday."
}回應中的變數會覆寫請求層級的變數,其他請求鍵則會保留。回應值為 null 時,會選用預留位置的預設值。合併後的物件也必須小於 32 KB。已儲存智慧體的回應僅接受
agent_id、variables、context、language,以及每通電話的
timezone;當你需要
取代提示詞或其他設定時,請回傳內嵌設定。已儲存智慧體的網路掛鉤
回應會在電話和小工具通話中使用智慧體已部署的 A/B 分流;
變數會在選擇變體後轉譯。當回應為非全雙工智慧體設定 language 時,
如果智慧體已為該語言設定語音,通話也會使用該語言專屬的語音。包含 prompt
的回應一律使用內嵌設定:該回應中的任何 agent_id 都會被忽略,包括 null 或
非整數的中繼資料。內嵌提示詞仍須通過一般驗證。
內嵌網路掛鉤回應也可以包含 variables 和 context。非字串或過長的 context
會導致交換失敗:電話通話會被拒絕,而小工具工作階段請求會以 400 失敗。已儲存智慧體的網路掛鉤
回應會在電話和小工具通話中使用智慧體已部署的 A/B 分流;
變數會在選擇變體後轉譯。對於撥入電話通話,請使用未指派撥入
智慧體的號碼,並設定其電話號碼或組織網路掛鉤;小工具金鑰使用
mode="webhook"。端點系統的傳入通知不會提供阻塞式
設定回應。
智慧體通話設定 Webhook
若要讓號碼持續指派給其智慧體,並只填入該通話的值,請為智慧體提供通話設定 Webhook。
在智慧體透過某個號碼接聽每通來電之前,Webhook 會取得通話以及智慧體的 ID、名稱和版本,並以與上述相同的
variables、context、language 和每通電話的 timezone 回應,不需要 agent_id。設定中使用沒有預設值的預留位置的智慧體,需要此 Webhook 才能接聽電話:Webhook 失敗時,通話不會開始。具有預設值的預留位置,例如 {{name|there}},則可讓智慧體在沒有此 Webhook 的情況下接聽電話。
SIP 標頭
透過 SIP(SIP 位址,或手動 SIP 連線上的號碼)接通至智慧體的通話,可在 X-* 與 User-to-User 標頭中攜帶情境資訊。每個標頭都會成為 sip_ 變數,例如 {{sip_x_amzn_connectcontactid}} 或 {{sip_uui}},且其優先順序最低:來自 API 或 webhook 的同名值會優先採用。請參閱透過 SIP 標頭傳遞通話情境。
標頭值由傳送端設定,因此應將其視為不受信任的內容,如同任何由瀏覽器提供的值。
Widget 工作階段 API
POST /v1/widget/session 接受頂層的 variables 與 language。其可發布金鑰會選取已儲存的智慧體。Webhook 模式金鑰會將這些值轉送至設定 Webhook,並如上所述合併回應。
由瀏覽器提供的 Widget variables 由用戶端控制,在完成上述驗證與字串清理後,會原樣轉送至 web.incoming,並回傳至完成 Webhook 與通話紀錄。請勿將其視為可信任的身分識別或授權資料。
Widget 自身的瀏覽器 context 欄位不同:它承載訪客所在頁面的文字,智慧體會將其視為網站內容(請參閱嵌入網頁 Widget)。Widget 通話的單次通話情境如上所述,來自 Webhook 模式金鑰的設定 Webhook。當通話同時具有兩者時,會先使用單次通話情境,再使用頁面內容。
Realtime 工作階段 API
POST /v1/realtime/sessions 可接受頂層的 variables、context 和 language,以及 agent_id 或內嵌 config:
{
"agent_id": 12,
"variables": {"name": "Ada"},
"context": "Ada is calling from the front desk about a guest's lost key card."
}context 僅能放在頂層;內嵌 config 會將其視為未知欄位而拒絕。
即時 WebSocket
使用已儲存的智慧體時,該智慧體已部署的提示詞會維持為其提示詞。
session.instructions 會成為通話的上下文,session.prompt.variables
(或 session.config.variables)會成為其變數,而 session.language
會成為每通通話的語言。在第一個 session.update 中透過
session.prompt.id 選擇智慧體;該更新送達後,即會啟動工作階段:
{
"type": "session.update",
"session": {
"type": "realtime",
"prompt": {"id": "12", "variables": {"name": "Ada"}},
"instructions": "Ada asked for a callback about her delivery window."
}
}連線 URL 中的 ?agent_id=12 會在 Socket 連線後立即啟動智慧體,早於任何
session.update,因此不會帶有每通通話的輸入。加入
&wait_for_session_update=1 即可等待第一個 session.update,並使用其中的
instructions 與 variables。
在內嵌工作階段中(沒有已儲存的智慧體),session.instructions 與先前相同,就是提示詞本身。瀏覽器測試通話和模擬會解析預設值與缺少的預留位置。若要使用特定值進行測試,請在智慧體上儲存一個通話設定範例,並在開始測試時選取它;通話會如同你的通話設定 Webhook 已使用該範例回應般執行。
通話結束後
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"]
}通話的 prompt_snapshot(GET /v1/calls/{call_id})會顯示已填入變數並新增內容區塊的智慧體提示詞。
將你的 CRM 或任務識別碼儲存在變數物件中,以便將已完成的通話連回其來源紀錄。變數和內容會隨通話紀錄保留;僅傳送適合保留在通話紀錄和 Webhook 中的資訊。
在驗證集、重播執行和調查中重播通話時,會使用該通話的變數和內容,以及受測提示詞,因此重播可測試該通話中的智慧體原本會獲得哪些資訊。
與既有提示詞的相容性
渲染也適用於現有已儲存的智慧體與 A/B 變體提示詞、內嵌的外撥與即時設定,以及由設定 Webhook 傳回的提示詞。未知的 {{name}} 預留位置會變成空白文字,即使未提供 variables 也一樣。上線前請檢查現有提示詞,包括 ThunderPhone 無法盤點的外部提供內嵌/Webhook 提示詞。
瀏覽器測試通話與模擬會套用相同的預設/空白行為,除非你選擇已儲存的通話設定範例。