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、空字串或只有空白字元,表示沒有 context。- 不是字串的值,或長度超過 20,000 個字元的值,會在通話及工作階段請求中以
400拒絕;如來自設定 webhook,則會如無效的variables一樣令交換失敗(見下文)。 - 系統會移除開頭及結尾的空白字元,並移除與變數值相同的控制字元及格式字元。
- Context 是通話提示的一部分,因此會計入通話的提示大小。
在 步驟 智能體中,內容會附加在通話內每個 智能體的提示詞後,而非每個步驟的指示後。
值的來源
外撥 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 路徑中,傳回你組織內已儲存的智能體,以及任何每通通話的值。對於全雙工智能體,即使通話以另一種支援語言開始,通話仍會保留該智能體的語音:每種語言的語音對應和原生語音切換均不適用於該通話。
{
"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;如需取代提示詞或其他設定,請傳回內嵌設定。已儲存智能體的 webhook
回應會在電話及小工具通話中使用智能體已部署的 A/B 分流;
變數會在選擇變體後代入。當回應為非 Full duplex 智能體設定 language 時,如智能體已為該語言設定語音,通話亦會使用該語言本身的語音。包含 prompt 的回應一律使用內嵌
設定:該回應中的任何 agent_id 都會被忽略,包括 null 或非整數的中繼資料。內嵌提示詞仍必須通過一般驗證。
內嵌 webhook 回應亦可包含 variables 及 context。如 context
不是字串或過長,該次交互便會失敗:電話通話會被拒絕,而小工具工作階段請求會以 400 失敗。已儲存智能體的 webhook
回應會在電話及小工具通話中使用智能體已部署的 A/B 分流;
變數會在選擇變體後代入。對於入站電話通話,請使用未指派入站
智能體的號碼,並設定其電話號碼或組織 webhook;小工具金鑰使用
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 模式金鑰的設定回調。當通話同時擁有兩者時,
會先使用每次通話內容,然後才使用頁面內容。
即時工作階段 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,並使用其中的
指示和變數。
在內嵌工作階段(沒有已儲存智能體)中,session.instructions 會如以往一樣作為提示詞本身。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"]
}該通話的 prompt_snapshot(GET /v1/calls/{call_id})會顯示已填入變數並加入內容區塊的智能體提示詞。
將你的 CRM 或工作識別碼儲存在變數物件中,以便將已完成的通話連結回其來源記錄。變數和內容會隨通話記錄一併保留;請只傳送適合保留於通話記錄及 webhook 的資訊。
在驗證集、重播執行及調查中重播通話時,會使用該通話的變數和內容,以及正在測試的提示詞,因此重播會測試該通話中的智能體原本會收到的資訊。
與現有提示詞的相容性
渲染功能同樣適用於現有已儲存智能體及 A/B 變體提示詞、內嵌外撥及即時設定,以及由設定 webhook 傳回的提示詞。即使未有提供 variables,未知的 {{name}} 佔位符亦會顯示為空白文字。推出前請檢查現有提示詞,包括 ThunderPhone 無法清點、由外部提供的內嵌/webhook 提示詞。Builder 咪高峰及模擬通話同樣採用預設值/空白的行為。