Open in

ThunderPhone mit OpenAI-Realtime-Clients verwenden

Richten Sie einen mit OpenAI Realtime kompatiblen Server-Client auf ThunderPhone aus und verwenden Sie dabei entweder einen gespeicherten Agenten oder eine Inline-Sitzungskonfiguration.

ThunderPhone implementiert eine gezielte Teilmenge des OpenAI-Realtime-Ereignismodells. Ein bestehender serverseitiger Client kann seinen WebSocket-, Audio-, Sitzungs- und Antwortereignisfluss beibehalten und gleichzeitig einen ThunderPhone-Sprachagenten verwenden.

Bevor Sie eine Verbindung herstellen

Sie benötigen einen geheimen API-Schlüssel einer ThunderPhone-Organisation und eine Server-Laufzeitumgebung, die WebSockets öffnen kann. Stellen Sie keine Verbindung über Browsercode her und legen Sie den Schlüssel nicht in einem Browser offen. Um einen gespeicherten Agenten zu verwenden, stellen Sie ihn zuerst bereit und kopieren Sie seine numerische Agent-ID.

Verbinden Sie sich mit:

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

Authentifizieren Sie das WebSocket-Upgrade über Ihren Server:

Authorization: Bearer sk_live_YOUR_API_KEY

Für Clients, die keine Handshake-Header setzen können, ist eine Authentifizierung über Query-Strings verfügbar. URLs können jedoch leichter in Protokolle gelangen.

Wählen Sie, wer die Konfiguration verwaltet

Modus	Verbinden mit	Konfigurationsquelle
Gespeicherter Agent	`?agent_id=12`	Bereitgestellter Prompt, Stimme, Produkt, Sprachen, Wissen und kompatible serverseitig ausgeführte Tools
Inline	Keine `agent_id`	Das erste akzeptierte `session.update` von Ihrem Client

Gespeicherter Agent

Verbinden Sie sich mit der bereitgestellten Agent-ID:

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

Der Agent startet, während der Socket eine Verbindung herstellt. Seine Begrüßung bleibt verfügbar, doch Realtime deaktiviert seine gesprochenen Stille-Check-ins und lässt transfer_call und send_keypad_input weg. Andere kompatible Tools werden auf ThunderPhone ausgeführt. Senden Sie für diesen Modus keine Inline-Anweisungen oder clientseitig ausgeführten Tools.

Legen Sie die Audioübertragung vor dem Start des Agenten mit den Abfrageparametern input_audio_format, output_audio_format, input_rate und output_rate fest. Nach der Verbindung können Sie die gespeicherte Konfiguration oder Audioformate nicht mehr ändern.

Inline-Sitzung

Warten Sie ohne agent_id auf session.created und senden Sie dann 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"
    }
  }
}

Die erste akzeptierte Aktualisierung richtet den Anruf ein. session.updated bedeutet, dass die Sitzung aktiv ist. Anweisungen, Stimme, Produkt, Tools und Audioformate können danach nicht mehr geändert werden.

Inline-Sitzungen haben keine automatische Begrüßung oder gesprochenen Stille-Check-ins. Damit der Agent zuerst spricht, fügen Sie eine System- oder Benutzernachricht hinzu und senden Sie response.create. Eine vollständig inaktive Sitzung endet weiterhin am Grenzwert der Plattform für stille Anrufe, standardmäßig nach 600 Sekunden.

Das offizielle OpenAI SDK verwenden

Übergeben Sie eine WebSocket-Basis-URL, die auf /v1 endet; das SDK hängt /realtime an. Der Wert model ist ein Kompatibilitätsname und wählt nicht das ThunderPhone- Produkt aus. Wählen Sie das Produkt in der Sitzungskonfiguration oder im gespeicherten Agenten.

Diese Verbindungsprüfung erstellt eine Inline-Bolt-Sitzung, gibt Ereignisse bis zum ersten session.updated aus und schließt dann die Verbindung. Verwenden Sie den minimalen Python- Client, um Audio zu 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())

Behalten Sie Ihre bestehende Verarbeitung für das Anhängen von Eingabeaudio, Antwortaudio-Deltas, Unterbrechungen, Funktionsaufrufe, Fehler und das saubere Schließen des Sockets bei. Inline-benutzerdefinierte Funktionen werden in Ihrem Client ausgeführt; geben Sie ihre Ergebnisse über das Realtime- Protokoll zurück. Tools gespeicherter Agenten werden auf ThunderPhone ausgeführt.

Sitzungslebenszyklus und Fehler

Ein WebSocket repräsentiert einen Anruf. Eine ungültige Agenten-ID oder abgelehnte Inline- Konfiguration erzeugt ein error-Ereignis. Warten Sie auf session.updated, bevor Sie die Sitzung als aktiv behandeln. Deklarieren Sie die tatsächlichen Ein- und Ausgabeformate sowie Abtastraten: Eine nicht übereinstimmende PCM-Rate gibt Audio zu schnell oder zu langsam wieder, anstatt einen Validierungsfehler zu erzeugen.

Nachdem die Sitzung gestartet ist, schließen Sie den Socket sauber, wenn Ihre Anwendung fertig ist. Inline-Sitzungen können clientseitig ausgeführte Funktionen verwenden. Sitzungen mit gespeicherten Agenten verwenden kompatible, von ThunderPhone ausgeführte Tools und bieten keine Weiterleitung oder Tastatureingabe.

Die Integration testen

Beginnen Sie mit dem minimalen Python-WAV-Client und einer Mono-PCM16-WAV-Datei mit der darin deklarierten Rate. Prüfen Sie Folgendes:

Der Server akzeptiert die Konfiguration und sendet session.updated.
Die Eingabe erzeugt Transkript- und Antwortaudio-Ereignisse mit der erwarteten Geschwindigkeit.
Unterbrechung und Abbruch der Antwort stoppen verbleibendes Ausgabeaudio.
Ergebnisse von Inline-Funktionen oder Tools gespeicherter Agenten werden an das Modell zurückgegeben.
Ungültige Eingaben erzeugen ein error-Ereignis, das Ihr Client verarbeitet.
Ihr Client schließt den Socket und der Anruf erscheint im Anruf- verlauf.

Die Realtime-WebSocket-Referenz listet die akzeptierten Ereignisse, Audioformate, Sitzungsfelder und vollständigen Beispiele auf.

Kosten

Realtime-Anrufe verwenden den normalen Minutentarif des ausgewählten Produkts. Die Aktivierung von Live- Transkript-Deltas fügt für die gesamte Sitzung einen Aufpreis pro Minute hinzu; den Tarif finden Sie unter Live- Transkripte und die Produkttarife unter Preise.

POST /v1/realtime/sessions ist ein separater verwalteter LiveKit-Pfad. Er erstellt einen Raum und ein bereichsbeschränktes Teilnehmer-Token; für eine direkte WebSocket-Verbindung ist er nicht erforderlich.

Informationen zu Framework-Integrationen finden Sie unter ThunderPhone mit Pipecat verwenden und ThunderPhone mit LiveKit Agents verwenden.