Gebruik ThunderPhone met OpenAI Realtime-clients

Laat een serverclient die compatibel is met OpenAI Realtime naar ThunderPhone verwijzen met een opgeslagen agent of een inline sessieconfiguratie.

ThunderPhone implementeert een gerichte subset van het OpenAI Realtime-gebeurtenismodel. Een bestaande client aan de serverzijde kan zijn eventstroom voor WebSocket, audio, sessies en reacties behouden terwijl deze een ThunderPhone-spraakagent gebruikt.

Voordat je verbinding maakt#

Je hebt een geheime API-sleutel voor je ThunderPhone-organisatie nodig en een serverruntime die WebSockets kan openen. Maak geen verbinding vanuit browsercode en stel de sleutel niet bloot aan een browser. Als je een opgeslagen agent wilt gebruiken, implementeer je deze eerst en kopieer je de numerieke agent-ID.

Maak verbinding met:

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

Verifieer de WebSocket-upgrade vanaf je server:

Authorization: Bearer sk_live_YOUR_API_KEY

Authenticatie via querystrings is beschikbaar voor clients die geen handshakeheaders kunnen instellen, maar URL's lekken gemakkelijker naar logboeken.

Kies wie eigenaar is van de configuratie#

Opgeslagen agent#

Maak verbinding met de ID van de geïmplementeerde agent:

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

De agent start terwijl de socket verbinding maakt. De begroeting blijft beschikbaar, maar Realtime schakelt de gesproken controles bij stilte uit en laat transfer_call en send_keypad_input weg. Andere compatibele tools worden uitgevoerd op ThunderPhone. Verstuur geen inline-instructies of door de client uitgevoerde tools voor deze modus.

Stel de audio voor overdracht in voordat de agent start met de queryparameters input_audio_format, output_audio_format, input_rate en output_rate. Je kunt de opgeslagen configuratie of audioformaten na verbinding niet wijzigen.

Inline-sessie#

Wacht zonder agent_id op session.created en verstuur vervolgens 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"
    }
  }
}

De eerste geaccepteerde update richt de oproep in. session.updated betekent dat de sessie actief is. Instructies, stem, product, tools en audioformaten kunnen daarna niet meer worden gewijzigd.

Inline-sessies hebben geen automatische begroeting of gesproken controles bij stilte. Als je wilt dat de agent als eerste spreekt, voeg je een systeem- of gebruikersbericht toe en verstuur je response.create. Een volledig inactieve sessie eindigt nog steeds bij de limiet voor stille oproepen van het platform, standaard 600 seconden.

Gebruik de officiële OpenAI SDK#

Geef een WebSocket-basis-URL door die eindigt op /v1; de SDK voegt /realtime toe. De waarde van model is een compatibiliteitsnaam en selecteert niet het ThunderPhone-product. Kies het product in de sessieconfiguratie of de opgeslagen agent.

Deze verbindingscontrole maakt een inline Bolt-sessie, toont gebeurtenissen tot de eerste session.updated en sluit vervolgens. Gebruik de minimale Python- client om audio te streamen.

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

Behoud je bestaande verwerking voor het toevoegen van invoeraudio, respons-audiodelta's, onderbrekingen, functieaanroepen, fouten en het netjes sluiten van de socket. Inline aangepaste functies worden uitgevoerd in je client; stuur hun resultaten terug via het Realtime- protocol. Tools van opgeslagen agents worden uitgevoerd op ThunderPhone.

Sessielevenscyclus en fouten#

Eén WebSocket vertegenwoordigt één oproep. Een ongeldige agent-ID of afgewezen inline configuratie veroorzaakt een error-gebeurtenis. Wacht op session.updated voordat je de sessie als actief beschouwt. Geef de daadwerkelijke invoer- en uitvoerformaten en samplefrequenties op: een afwijkende PCM-frequentie speelt audio te snel of te langzaam af in plaats van een validatiefout te veroorzaken.

Sluit de socket netjes wanneer je toepassing klaar is nadat de sessie is gestart. Inline sessies kunnen functies gebruiken die door de client worden uitgevoerd. Sessies met opgeslagen agents gebruiken compatibele tools die op ThunderPhone worden uitgevoerd en bieden geen doorschakeling of toetsenbordinvoer.

Test de integratie#

Begin met de minimale Python WAV-client en een mono PCM16 WAV met de opgegeven frequentie. Controleer het volgende:

1. De server accepteert de configuratie en stuurt session.updated.
2. Invoer produceert transcriptie- en respons-audiogebeurtenissen met de verwachte snelheid.
3. Onderbreking en annulering van een respons stoppen resterende uitvoeraudio.
4. Resultaten van inline functies of tools van opgeslagen agents worden teruggestuurd naar het model.
5. Ongeldige invoer veroorzaakt een error-gebeurtenis die je client verwerkt.
6. Je client sluit de socket en de oproep verschijnt in de Oproepgeschiedenis.

De Realtime WebSocket-referentie bevat de geaccepteerde gebeurtenissen, audioformaten, sessievelden en volledige voorbeelden.

Kosten#

Realtime-oproepen gebruiken het normale tarief per minuut van het geselecteerde product. Het inschakelen van live transcriptdelta's voegt een toeslag per minuut toe voor de hele sessie; zie Live transcripties voor het tarief en Prijzen voor producttarieven.

POST /v1/realtime/sessions is een afzonderlijk beheerd LiveKit-pad. Het maakt een ruimte en een scoped deelnemertoken; het is niet vereist voor een directe WebSocket- verbinding.

Zie voor frameworkintegraties Gebruik ThunderPhone vanuit Pipecat en Gebruik ThunderPhone vanuit LiveKit Agents.