Open in
使用 ThunderPhone 配合 OpenAI Realtime 用戶端
將與 OpenAI Realtime 相容的伺服器用戶端連接至 ThunderPhone,可使用已儲存的智能體或內嵌工作階段設定。
ThunderPhone 實作了 OpenAI Realtime 事件模型中一個專注的子集。 現有的伺服器端客戶端可在使用 ThunderPhone 語音智能體時,保留其 WebSocket、音訊、工作階段及回應事件流程。
連接前準備
你需要 ThunderPhone 組織私密 API 金鑰,以及可開啟 WebSocket 的伺服器運行環境。 請勿從瀏覽器程式碼連接,亦不要向瀏覽器公開金鑰。若要使用已儲存的智能體,請先部署,然後複製其數字智能體 ID。
連接至:
wss://api.thunderphone.com/v1/realtime從你的伺服器驗證 WebSocket 升級請求:
Authorization: Bearer sk_live_YOUR_API_KEY對於無法設定握手標頭的客戶端,可使用查詢字串驗證;但 URL 較容易洩漏至日誌。
選擇由誰管理設定
| 模式 | 選擇方式 | 設定來源 |
|---|---|---|
| 已儲存智能體 | 在首次 session.update 中使用 session.prompt.id,或使用 ?agent_id=12 | 已部署的提示詞、語音、產品、語言、知識及相容的伺服器端執行工具,以及此工作階段的指示和變數 |
| 內嵌 | 兩者皆非 | 客戶端首次被接受的 session.update |
已儲存智能體
將每次通話共用的內容保留在已儲存智能體中,其中包含版本及測試集,並在首次 session.update 中傳送每個工作階段有所變更的內容:session.prompt.id 選擇已部署的智能體,session.instructions 傳遞此工作階段的簡述,而 session.prompt.variables 會填入智能體提示詞中的 {{name}} 佔位符。
{
"type": "session.update",
"session": {
"type": "realtime",
"prompt": {
"id": "12",
"variables": { "user_name": "Ada Park" }
},
"instructions": "Ada is a Costco member in Mountain View. Call the store and ask for today's opening hours.",
"audio": {
"input": { "format": { "type": "audio/pcm", "rate": 24000 } },
"output": { "format": { "type": "audio/pcm", "rate": 24000 } }
}
}
}指示會成為通話的內容,僅在此次通話中加入於智能體提示詞之後。工作階段本身的選項
(telephony、outbound、ivr_mode、call_events、placeholders)及其啟動時使用的語言
(primary_language)會如內嵌工作階段一樣置於 session.config。智能體的聲音、產品及工具均來自其已部署的設定:更新中的聲音、其他智能體設定,或僅限 OpenAI 的欄位(例如非預設的 tool_choice)會產生 error 事件並被忽略,而由你的客戶端執行的工具會被拒絕(客戶端執行的工具需要使用內嵌工作階段)。prompt.version 會被接受但忽略。請參閱使用已儲存智能體了解所有規則。
改為使用 ?agent_id=12 連線時,智能體會在 socket 連線期間啟動,因此無需 session.update,但其工作階段設定其後會固定:其後傳送的指示、變數及工作階段選項(outbound、ivr_mode、telephony、placeholders、call_events)會以 error 事件拒絕。將
&wait_for_session_update=1 加入 URL,便可改為在首次
session.update 時才啟動,並以相同方式傳遞指示、變數及工作階段選項;撥出工作階段必須使用此方式。在該更新抵達前,來電者音訊會被暫緩處理,其他事件會被拒絕,如 10 秒內未收到更新,socket 便會關閉。
問候語仍可使用,但 Realtime 會停用智能體在靜默期間作出的口頭跟進,並只會在啟用
call_events 時提供 transfer_call 及 send_keypad_input。其他相容工具會在 ThunderPhone 上執行;客戶端執行的工具需要使用內嵌工作階段。通話開始後,音訊格式以及工作階段的指示和變數均不可更改。
內嵌工作階段
如未儲存智能體,請等待 session.created,然後傳送 session.update:
{
"type": "session.update",
"session": {
"type": "realtime",
"instructions": "Answer questions clearly and keep responses brief.",
"audio": {
"input": {
"format": { "type": "audio/pcm", "rate": 24000 }
},
"output": {
"format": { "type": "audio/pcm", "rate": 24000 },
"voice": "olivia"
}
},
"config": {
"product": "bolt"
}
}
}首個獲接受的更新會配置通話。session.updated 表示工作階段已啟用。其後無法變更指示、語音、產品、工具及音訊格式。若要固定指示並只更改具名值,請在指示中加入 {{name}} 佔位符,並在 session.config.variables 中傳送相應值。
內嵌工作階段不設自動問候語或語音靜默提示。若要讓智能體首先說話,請附加系統或使用者訊息,然後傳送
response.create。完全閒置的工作階段仍會在平台的靜默通話上限時結束,預設為 600 秒。
使用官方 OpenAI SDK
傳入以 /v1 結尾的 WebSocket 基礎 URL;SDK 會附加 /realtime。model 值為相容性名稱,不會選擇 ThunderPhone
產品。請在工作階段設定或已儲存的智能體中選擇產品。
此連線檢查會建立內嵌 Bolt 工作階段、列印事件直至第一個
session.updated,然後關閉連線。使用最精簡 Python
用戶端串流音訊。
import asyncio
import os
from openai import AsyncOpenAI
async def main():
client = AsyncOpenAI(
api_key=os.environ["THUNDERPHONE_API_KEY"],
websocket_base_url="wss://api.thunderphone.com/v1",
)
async with client.realtime.connect(
model="thunderphone-realtime"
) as connection:
await connection.session.update(session={
"type": "realtime",
"instructions": "Listen to the caller and help them complete the call.",
"config": {"product": "bolt"},
})
async for event in connection:
print(event.type)
if event.type == "session.updated":
break
if __name__ == "__main__":
asyncio.run(main())保留你現有的輸入音訊附加、回應音訊增量、中斷、函數呼叫、錯誤及正常關閉 socket 的處理方式。內嵌自訂函數會在你的用戶端執行;請透過 Realtime 協定傳回結果。已儲存智能體的工具會在 ThunderPhone 上執行。
工作階段生命週期及故障
每個 WebSocket 代表一通電話。無效的智能體 ID 或遭拒絕的內嵌設定會產生 error 事件。在收到 session.updated 前,不應將工作階段視為已啟用。請宣告實際的輸入及輸出格式與取樣率:PCM 取樣率不符會令音訊播放過快或過慢,而不會產生驗證錯誤。
會話啟動後,當你的應用程式完成工作時,請妥善關閉通訊端。內嵌會話可使用由客戶端執行的函式。已儲存智能體會話使用相容、由 ThunderPhone 執行的工具,並只有配合 call_events 才提供 transfer_call(以及外撥會話中的 send_keypad_input);你的客戶端會執行這些 call.* 事件。
測試整合
先使用最精簡 Python WAV 用戶端 及符合其已宣告取樣率的單聲道 PCM16 WAV。請確認:
- 伺服器接受設定並傳送
session.updated。 - 輸入會以預期速度產生逐字稿及回應音訊事件。
- 中斷及取消回應會停止餘下的輸出音訊。
- 內嵌函數結果或已儲存智能體工具結果會傳回至模型。
- 無效輸入會產生由你的用戶端處理的
error事件。 - 你的用戶端會關閉 socket,且通話會顯示於通話記錄。
Realtime WebSocket 參考文件列出可接受的 事件、音訊格式、工作階段欄位及完整範例。
費用
Realtime 通話的定價方式與其他通話相同:按其組件在我們供應商標價中的成本計算,另加基礎設施費用及 17–25% 利潤率。啟用即時轉錄增量會為整個工作階段增加轉錄處理工作;請參閱即時轉錄及定價。
POST /v1/realtime/sessions 是獨立管理的 LiveKit 路徑。它會建立房間及具範圍限制的參與者權杖;直接 WebSocket 連線不需要使用它。
如需框架整合,請參閱從 Pipecat 使用 ThunderPhone 及從 LiveKit Agents 使用 ThunderPhone。