ThunderPhone v3 現已上線。自助開通,價格低至每分鐘 2¢。查看公告

Developer cookbook

每次通話的變數與背景資料

為每次通話提供專屬詳情,可作為提示詞的具名變數或自由格式簡報,毋須更改智能體。

每次通話均可附帶兩類單次通話輸入。你可單獨使用其中一類,或同時使用兩類:

  • 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 咪高峰及模擬通話同樣採用預設值/空白的行為。