Använd ThunderPhone med OpenAI Realtime-klienter

Anslut en OpenAI Realtime-kompatibel serverklient till ThunderPhone med antingen en sparad agent eller infogad sessionskonfiguration.

ThunderPhone implementerar en fokuserad delmängd av OpenAI Realtime-händelsemodellen. En befintlig klient på serversidan kan behålla sitt flöde för WebSocket-, ljud-, sessions- och svarshändelser medan den använder en ThunderPhone-röstagent.

Innan du ansluter#

Du behöver en hemlig API-nyckel för ThunderPhone-organisationen och en servermiljö som kan öppna WebSocket-anslutningar. Anslut inte från webbläsarkod och exponera inte nyckeln för en webbläsare. Om du vill använda en sparad agent distribuerar du den först och kopierar dess numeriska agent-ID.

Anslut till:

wss://api.thunderphone.com/v1/realtime

Autentisera WebSocket-uppgraderingen från din server:

Authorization: Bearer sk_live_YOUR_API_KEY

Autentisering med frågesträng finns för klienter som inte kan ange handskakningsrubriker, men URL:er är enklare att läcka till loggar.

Välj vem som äger konfigurationen#

Sparad agent#

Anslut med det distribuerade agent-ID:t:

wss://api.thunderphone.com/v1/realtime?agent_id=12

Agenten startar medan socketen ansluter. Dess hälsning är fortfarande tillgänglig, men Realtime inaktiverar dess talade avstämningar vid tystnad och utelämnar transfer_call och send_keypad_input. Andra kompatibla verktyg körs på ThunderPhone. Skicka inte inline-instruktioner eller verktyg som körs av klienten i detta läge.

Ange ljudformat för överföringen innan agenten startar med frågeparametrarna input_audio_format, output_audio_format, input_rate och output_rate. Du kan inte ändra den sparade konfigurationen eller ljudformaten efter anslutningen.

Inline-session#

Utan agent_id väntar du på session.created och skickar sedan 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"
    }
  }
}

Den första godkända uppdateringen etablerar samtalet. session.updated betyder att sessionen är aktiv. Instruktioner, röst, produkt, verktyg och ljudformat kan inte ändras efter den punkten.

Inline-sessioner har ingen automatisk hälsning eller talade avstämningar vid tystnad. För att få agenten att tala först lägger du till ett system- eller användarmeddelande och skickar response.create. En helt inaktiv session avslutas fortfarande vid plattformens gräns för tysta samtal, som är 600 sekunder som standard.

Använd det officiella OpenAI SDK:t#

Ange en WebSocket-bas-URL som slutar på /v1; SDK:t lägger till /realtime. Värdet model är ett kompatibilitetsnamn och väljer inte ThunderPhone-produkten. Välj produkten i sessionskonfigurationen eller i den sparade agenten.

Den här anslutningskontrollen skapar en inbäddad Bolt-session, skriver ut händelser tills den första session.updated och stänger sedan anslutningen. Använd den minimala Python- klienten för att strömma ljud.

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())

Behåll din befintliga hantering för tillägg av inmatningsljud, ljuddeltan för svar, avbrott, funktionsanrop, fel och korrekt stängning av socketen. Anpassade inline- funktioner körs i din klient; returnera deras resultat via Realtime-protokollet. Verktyg för sparade agenter körs på ThunderPhone.

Sessionslivscykel och fel#

En WebSocket representerar ett samtal. Ett ogiltigt agent-ID eller en avvisad inline- konfiguration genererar en error-händelse. Vänta på session.updated innan du betraktar sessionen som aktiv. Ange de faktiska in- och utdataformaten samt samplingsfrekvenserna: en PCM-frekvens som inte matchar spelar upp ljud för snabbt eller för långsamt i stället för att skapa ett valideringsfel.

När sessionen har startat ska du stänga socketen korrekt när din applikation är klar. Inline-sessioner kan använda funktioner som körs i klienten. Sessioner med sparade agenter använder kompatibla verktyg som körs av ThunderPhone och erbjuder inte vidarekoppling eller knappsatsinmatning.

Testa integrationen#

Börja med den minimala Python WAV-klienten och en mono PCM16 WAV med dess angivna frekvens. Kontrollera:

1. Servern accepterar konfigurationen och skickar session.updated.
2. Indata genererar transkriptions- och svarsljudshändelser med förväntad hastighet.
3. Avbrott och avbrytning av svar stoppar återstående utgående ljud.
4. Resultat från inline-funktioner eller verktyg för sparade agenter returneras till modellen.
5. Ogiltiga indata genererar en error-händelse som din klient hanterar.
6. Din klient stänger socketen och samtalet visas i Samtalshistorik.

Realtime WebSocket-referensen listar accepterade händelser, ljudformat, sessionsfält och kompletta exempel.

Kostnad#

Realtime-samtal använder den valda produktens ordinarie minutpris. Aktivering av live-transkriptionsdeltan lägger till en minutbaserad avgift för hela sessionen; se Live-transkriptioner för priset och Priser för produktpriser.

POST /v1/realtime/sessions är en separat hanterad LiveKit-rutt. Den skapar ett rum och en deltagartoken med begränsad omfattning; den krävs inte för en direkt WebSocket-anslutning.

För ramverksintegrationer, se Använd ThunderPhone från Pipecat och Använd ThunderPhone från LiveKit Agents.