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

Connect tools & data

使用 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。請確認:

  1. 伺服器接受設定並傳送 session.updated。
  2. 輸入會以預期速度產生逐字稿及回應音訊事件。
  3. 中斷及取消回應會停止餘下的輸出音訊。
  4. 內嵌函數結果或已儲存智能體工具結果會傳回至模型。
  5. 無效輸入會產生由你的用戶端處理的 error 事件。
  6. 你的用戶端會關閉 socket,且通話會顯示於通話記錄。

Realtime WebSocket 參考文件列出可接受的 事件、音訊格式、工作階段欄位及完整範例。

費用

Realtime 通話的定價方式與其他通話相同:按其組件在我們供應商標價中的成本計算,另加基礎設施費用及 17–25% 利潤率。啟用即時轉錄增量會為整個工作階段增加轉錄處理工作;請參閱即時轉錄及定價。

POST /v1/realtime/sessions 是獨立管理的 LiveKit 路徑。它會建立房間及具範圍限制的參與者權杖;直接 WebSocket 連線不需要使用它。

如需框架整合,請參閱從 Pipecat 使用 ThunderPhone 及從 LiveKit Agents 使用 ThunderPhone。