Wähle deine API aus, um zu sehen, wie du die Verbindung herstellst und welche Sitzungsereignisse du empfängst.
Eine GPT-Live-Sitzung von deinem Server aus steuern
Verbinde deinen Anwendungsserver mit einer bestehenden WebRTC- oder SIP-Sitzung von GPT-Live, wenn der Server Gesprächsereignisse empfangen, private Tools ausführen oder das Gespräch aktualisieren soll. Diese zweite Verbindung heißt Sideband-WebSocket. Beide Verbindungen gehören zur selben Sitzung. Die primäre Audioübertragung läuft über WebRTC oder SIP.
Der Sideband-Kanal überträgt Ereignisse und Befehle. Deine Anwendung führt Tools aus, prüft Berechtigungen und wendet Geschäftsregeln an. Bewahre API-Schlüssel und Zugangsdaten für Tools auf deinem Server auf.
Entscheiden, ob du einen Sideband-Kanal brauchst
Verwende in Browseranwendungen den WebRTC-Datenkanal für Untertitel und lokale Aktualisierungen der Benutzeroberfläche. Nutze einen Sideband-Kanal, wenn dein Server Transkripte verarbeitet, etwa um Schutzregeln anzuwenden, die Stimmung zu analysieren oder vorsorglich Tools aufzurufen. Dein Server kann Ereignisse empfangen und dieselbe Sitzung direkt steuern, während der Browser Audio weiterhin über WebRTC überträgt. Beispiele findest du im Abschnitt Auf Transkriptfragmente reagieren.
Wenn dein Backend Audio über die primäre WebSocket-Verbindung streamt, nutze diese Verbindung auch, um Ereignisse zu empfangen und Befehle zu senden.
Die Delegation an Responses funktioniert auch ohne Sideband-Kanal. Der Browser kann Ereignisse für Funktionsaufrufe von seinem Datenkanal an ein authentifiziertes Backend weiterleiten, das die Funktionen ausführt. Von OpenAI gehostete Tools werden über das Backend ausgeführt, an das du delegiert hast. Deine Anwendung braucht dafür keine eigene Ausführungslogik.
Verbindung zur bestehenden Sitzung herstellen
-
Speichere die ID der Sitzung, die dein Backend steuern soll. Verwende bei WebRTC oder einem ausgehenden SIP-Anruf den Wert
session.idaus der JSON-Antwort aufPOST /v1/live/sessions. Bei eingehenden SIP-Anrufen musst du zuerst den Anruf annehmen. Verwende danndata.session_idaus dem zugehörigen Webhook. Speichere die ID in deiner Anwendung zusammen mit den Daten zum Benutzerkonto und zum Gespräch. -
Öffne von deinem Server aus einen WebSocket unter der folgenden URL. Setze die gespeicherte ID unverändert ein. Authentifiziere dich mit
Authorization: Bearer $OPENAI_API_KEYund verwende dabei dieselben Projektzugangsdaten wie beim Erstellen oder Annehmen der Sitzung. Sende dieselben Verbindungsheader mit, die beim Erstellen der Sitzung erforderlich sind.wss://api.openai.com/v1/live/sessions/{session_id}/attach -
Empfange Ereignisse und sende Befehle über den verbundenen Socket. Die Sitzung läuft bereits. Sende
session.startkein zweites Mal.
Übernimm die Sitzungs-ID samt Präfix unverändert. Prüfe, ob deine Anwendung auf diese Sitzung zugreifen darf.
Erneute Übertragung beim Verbindungsaufbau
Bei jedem Verbindungsaufbau überträgt der Sideband-Kanal zunächst die Ereignisse der vorangegangenen 3 Sekunden erneut. Danach überträgt er neue Ereignisse. Dieses Zeitfenster gilt für Gesprächsereignisse, Ereignisse zum Anrufverlauf und Kopien der Ein- und Ausgabeaudiodaten. Ereignisse, die älter als 3 Sekunden sind, werden nicht erneut übertragen. Stelle die Verbindung deshalb frühzeitig her und speichere den früheren Verlauf, soweit deine Anwendung ihn benötigt.
Erneut übertragene Ereignisse behalten ihre ursprüngliche event_id, sofern sie eine haben. Erkenne Duplikate anhand der event_id und überspringe sie, insbesondere nach einem erneuten Verbindungsaufbau. So vermeidest du, dass Tools oder andere Aktionen mehrfach ausgeführt werden. Ereignisse mit Kopien der Audiodaten enthalten keine event_id. Welche Felder Zeitangaben enthalten, erfährst du im Abschnitt Kopien der Audiodaten empfangen.
Ereignisse verfolgen und Befehle senden
| Aufgabe | Ereignisse oder Befehle |
|---|---|
| Gespräch verfolgen | Empfange Transkriptdeltas für die Beiträge beider Gesprächsseiten, Delegationsereignisse und verschachtelte Responses-Ereignisse. |
| Backend-Konfiguration aktualisieren | Ändere mit session.update die unterstützten Einstellungen im bestehenden Delegationsmodus. Starteinstellungen wie das Frontend-Modell und die Audiokonfiguration bleiben fest. |
| Kontext bereitstellen | Verwende session.instructions.append für Anweisungen, session.thinking.append für Kontext, der nicht ausgesprochen wird, und session.commentary.append für Mitteilungen, die das Modell aussprechen kann. |
| Tool-Ergebnisse zurückgeben | Sende bei der Delegation an Responses zuerst response.item.create und dann response.create, damit das Backend die Arbeit fortsetzt. |
| Mikrofoneingang steuern | Verwende session.input_audio.mute und session.input_audio.unmute. Wenn du den Eingang stummschaltest, läuft die Ausgabe des Assistenten weiter. |
| Sitzung beenden | Sende session.close und warte auf session.closed, bevor du die Verbindung trennst. |
Für Befehle gelten dieselben Validierungs- und Delegationsregeln wie auf der primären Verbindung. Wenn du allgemeinen Sitzungskontext ergänzt, verwende delegation_id: null. Jede ID mit einem anderen Wert muss eine bestehende Delegation des Clients bezeichnen. Informationen zur Konfiguration und Funktionsausführung sowie Beispiele zum Ergänzen von Kontext findest du unter Delegation und Tools.
Übertrage bei Browsersitzungen die Mikrofoneingabe und die Lautsprecherausgabe weiterhin über die ausgehandelte WebRTC-Medienspur. Nutze den Sideband-Kanal für Gesprächsereignisse und zur Steuerung. Verfolge die Wiedergabe in deinem Audioplayer.
Kopien der Audiodaten empfangen
Über den Sideband-Kanal erhältst du Kopien der Ein- und Ausgabeaudiodaten, auch aus dem Zeitfenster für die erneute Übertragung. Die primäre Verbindung überträgt weiterhin die Live-Medien.
| Ereignis | Audiofeld | Zeitangaben |
|---|---|---|
session.input_audio.append |
audio |
Keine Zeitstempel. |
session.output_audio.delta |
delta |
start_ms und end_ms geben an, welchen Zeitraum die Ausgabe auf der Zeitachse der Sitzung abdeckt. |
Beide Ereignisse enthalten Base64-kodierte Mono-Rohdaten im Format PCM16LE mit 24 kHz, unabhängig vom Audioformat der primären Verbindung. Keines der beiden Ereignisse enthält eine event_id. Die Kopie der Eingabe enthält das empfangene Audiosignal vor der Stummschaltung. Daraus lässt sich nicht ableiten, ob das Modell diese Samples verarbeitet hat. In den Zeitbereichen der Ausgabekopien können Lücken entstehen, wenn Frames verworfen wurden. Die Zeitangaben sagen nichts darüber aus, wann die anrufende Person das Audio gehört hat.
Sende Mikrofon-Audio ausschließlich über die primäre Verbindung. Nutze den Sideband-Kanal, um Kopien der Audiodaten zu empfangen.
Für jede Aktion eine Zuständigkeit festlegen
Lege für jede Aktion fest, ob der Browser oder das Backend sie übernimmt. Wenn beide Verbindungen ein Ereignis für denselben Funktionsaufruf empfangen, führe die Funktion nur einmal aus. Lege die Zuständigkeit ebenso für Kontextaktualisierungen und für Anfragen fest, mit denen das Backend seine Arbeit fortsetzen soll.
Stelle die Verbindung frühzeitig her, wenn das Backend das Gespräch von Anfang an verfolgen soll. Speichere Transkripte und den Zustand der Tools in deiner Anwendung, einschließlich des Verlaufs, den du vor dem Verbindungsaufbau erfasst hast.
Auch bei aktivem Sideband-Kanal kann der Browser weiterhin Sitzungsereignisse empfangen. Bewahre sensible Zugangsdaten für Tools im Backend auf und entscheide dort über Berechtigungen. Gib nur den Kontext zurück, den das Gespräch erfordert.
Schutzregeln für Gespräche anwenden
Nutze den primären WebSocket oder den Sideband-Kanal deines Servers, um das Gespräch zu verfolgen und Anfragen anhand der Richtlinien deiner Anwendung zu prüfen. Deine Anwendung führt die Prüfungen durch. Schlägt eine Schutzregel an, blockiert die Anwendung die betroffenen Aktionen und sendet korrigierende Anweisungen.
Prüfungen parallel zum Gespräch ausführen
Schutzregeln lassen sich anwenden, indem du Transkriptfragmente direkt beim Empfang verarbeitest. Mit demselben Datenstrom kannst du parallel zu den Prüfungen vorsorglich eine Abfrage starten oder die Benutzeroberfläche aktualisieren.
- Transkripte überwachen. Sammle die Fragmente aus
session.input_transcript.delta, um Anfragen auf Jailbreak-Versuche, sensible Informationen oder Richtlinienverstöße zu prüfen. Prüfe mitsession.output_transcript.delta, ob die Sprachausgabe des Assistenten unbelegte Aussagen oder Antworten enthält, die außerhalb des Aufgabenbereichs deiner Anwendung liegen. Ordne jede Prüfung dem Transkript und der Anfrage in deiner Anwendung zu, auf die sie sich bezieht. - Prüfungen parallel ausführen. Ein schnelles, ressourcensparendes Modell kann Anfragen prüfen, während das Gespräch weiterläuft. Gib ein kompaktes strukturiertes Ergebnis wie
{"triggered": true}zurück, auf das deine Anwendung reagieren kann. Führe Aktionen, die eine Genehmigung erfordern, erst aus, wenn sie alle zugehörigen Prüfungen bestanden haben. Schlägt eine Prüfung fehl oder läuft ihre Frist ab, müssen die Aktionen blockiert bleiben. - Betroffene Aktionen blockieren. Wenn eine Schutzregel anschlägt, markiere die Anfrage im Anwendungszustand als blockiert. Prüfe diesen Zustand, bevor du ein Tool ausführst oder eine Änderung verbindlich übernimmst. Das gilt auch für Aufträge, die bereits in der Warteschlange stehen.
- Zugehörige Vorgänge stoppen. Brich Aufträge deiner Anwendung ab, sofern dein Backend das unterstützt. Verwirf verspätete Ergebnisse blockierter oder inzwischen ersetzter Anfragen. Stoppe bei der Delegation an Responses die Ausführung betroffener benutzerdefinierter Funktionen und sende kein
response.create, um blockierte Vorgänge fortzusetzen. Eine bereits laufende gehostete Antwort wird dadurch nicht abgebrochen. Auch die Sprachausgabe im Frontend läuft weiter. - Entscheidung protokollieren und Gespräch umlenken. Protokolliere die Entscheidung mit den IDs der betroffenen Anfrage und Delegation. Sende anschließend eine korrigierende Anweisung.
Wie du Fragmente sammelst, erfährst du unter Transkriptdeltas. Der Abschnitt Delegation und Tools beschreibt, wie du sicherstellst, dass Backend-Ergebnisse zur aktuellen Aufgabe passen.
Das Gespräch umlenken
Verwende session.instructions.append, um das Gespräch anhand deiner Schutzregeln zu steuern. Der Befehl kann die laufende Sprachausgabe unterbrechen und eine neue Anweisung anwenden. Nachdem deine Anwendung eine Anfrage blockiert hat, kannst du beispielsweise folgenden Befehl senden.
import type { ClientEvent } from "openai/resources/live/live";
export function sendUpdate(connection: { send: (event: ClientEvent) => void }) {
connection.send({
type: "session.instructions.append",
event_id: "guardrail_block_17",
delegation_id: null,
content:
"Stop speaking immediately. Do not continue or act on the last request. Refuse briefly, then wait.",
});
}Lass deine Anwendung die Anweisung formulieren. Übernimm keinen Text aus nicht vertrauenswürdigen Nutzereingaben als Anweisung. Verwende delegation_id: null, damit die Korrektur für die gesamte Sitzung gilt, und begrenze content auf höchstens 500 Token.
Ordne session.instructions.appended über client_event_id deinem Befehl zu. Die Bestätigung trifft nach dem geschätzten Zeitpunkt ein, zu dem die Anweisung in den Kontext aufgenommen wurde. Um zu verhindern, dass die anrufende Person das Audio hört, steuere die Wiedergabe wie im folgenden Abschnitt beschrieben.
Verwende Anweisungen auch für Hinweise, die mit einem bestimmten Wortlaut gesprochen werden sollen. Ein Beispiel und Hinweise zur Wiedergabe findest du unter Einen Hinweis ausgeben.
Wiedergabe bei Bedarf steuern
Wenn deine Anwendung die Audioausgabe des Modells blockieren muss, steuere die Wiedergabe im Client oder im Medien-Relay. Schalte die Ausgabe vorübergehend stumm oder verwirf sie, leere die lokale Audiowarteschlange und sende die korrigierende Anweisung. Entferne veraltete Audiodaten, bevor du die Wiedergabe gemäß den Regeln deiner Anwendung wieder aufnimmst. Die Bestätigung der Anweisung ist kein Signal zur Wiederaufnahme. Über den Sideband-Kanal allein lässt sich die Wiedergabe nicht steuern. Korrigierende Anweisungen können bereits Gehörtes nicht rückgängig machen.
session.input_audio.mute steuert den Mikrofoneingang der anrufenden Person. Der Befehl schaltet weder die Modellausgabe stumm noch bricht er delegierte Vorgänge ab.
Sprachausgabe vor der Wiedergabe prüfen
Für die meisten Anwendungen empfiehlt es sich, die Transkripte beider Gesprächsseiten zu überwachen, während das Gespräch weiterläuft. Schlägt eine Schutzregel an, kann deine Anwendung die betroffenen Aktionen blockieren oder korrigierende Anweisungen senden.
Wenn deine Anwendung die Sprachausgabe des Assistenten vor der Wiedergabe prüfen muss, puffere die Audiodaten in deinem Player oder deiner Medienbrücke, bevor du sie an die anrufende Person sendest. Empfange während der Prüfung weiterhin Audio- und Transkriptereignisse und lies die Transkripte unabhängig von der Wiedergabe aus.
- Audio und zugehöriges Transkript erfassen. Implementiere in deiner Anwendung eine Sprachaktivitätserkennung (VAD) für die Ausgabe oder nutze ein Noise-Gate deines Medienframeworks, um mögliche Sprachsegmente zu erkennen. GPT-Live stellt für diesen Ablauf weder eine VAD für die Ausgabe noch ein Noise-Gate bereit. Warte für jedes Segment auf das Transkript, das du für die Prüfung benötigst.
- Audio zur Wiedergabe freigeben. Wenn ein Segment die Prüfung besteht, stelle seine ursprünglich gepufferten Audiodaten in die Wiedergabewarteschlange. Schlägt die Prüfung fehl, fehlt das Transkript oder läuft die Prüffrist ab, verwirf das Segment und verwende die sichere Ausweichlösung, die du für deine Anwendung festgelegt hast.
- Unterbrechungen berücksichtigen. Ordne Audio, Transkript, Prüfergebnis und Wiedergabestatus einer von deiner Anwendung erzeugten ID zu. Wenn eine Unterbrechung die betreffende Sprachausgabe abbricht, entferne die zugehörigen Audiodaten aus Puffer und Warteschlange. Ignoriere alle Freigaben, die dafür später eintreffen.
Eine Sprechpause kann ein mögliches Segment abgrenzen, obwohl das Modell seine Antwort noch formuliert. Wenn deine Richtlinie die Prüfung einer vollständigen Antwort verlangt, lege fest, woran deine Anwendung das Ende der Antwort erkennt. Die Sprachaktivitätserkennung allein kann nicht feststellen, ob die gesamte Antwort abgeschlossen ist.
Die Pufferung erhöht die Latenz. Verworfene Sprachsegmente bleiben im Gesprächskontext des Modells. Teste daher, wie das Gespräch weitergeht, wenn deine Anwendung Audio zurückhält oder auf die Ausweichlösung zurückgreift.
Eingriffe testen
Teste zulässige und blockierte Anfragen, Fehlalarme, langsame oder fehlgeschlagene Prüfungen sowie verspätete Ergebnisse abgebrochener Vorgänge. Teste auch, was passiert, wenn eine Schutzregel während der Sprachausgabe oder der Ausführung eines Tools anschlägt. Prüfe getrennt, ob die Anwendung Aktionen blockiert, den richtigen Zustand erfasst, die korrigierende Sprachausgabe erzeugt und diese tatsächlich wiedergibt. Wenn du die Ausgabe steuerst, teste auch den Umgang mit Audio in der Warteschlange und die Wiederaufnahme der Wiedergabe. Nutze das Cookbook zur Evaluierung von Sprachagenten, um den Erfolg bei der Aufgabenbearbeitung und die Zeit bis zur gesprochenen Antwort zu vergleichen.
Sitzung geordnet beenden
Empfange weiterhin Ereignisse, während Tools ihre Arbeit abschließen und die Sitzung die endgültigen Nutzungsdaten meldet. Registriere den Handler für session.closed, bevor du session.close sendest. Halte die WebRTC-Verbindung, den Datenkanal und den Sideband-Kanal offen, bis alle ausstehenden Vorgänge abgeschlossen sind. Speichere vor dem Aufräumen die endgültigen Nutzungsdaten der Sitzung und alle Nutzungsdaten des Backends, die du in Responses-Ereignissen empfangen hast. Bricht die Verbindung vor dem letzten Ereignis ab, vermerke, dass die Sitzung nicht vollständig abgeschlossen wurde. Den Ablauf beim Beenden findest du unter Sitzungen verwalten.
Mit der Realtime API können Clients über WebRTC oder SIP direkt eine Verbindung zum API-Server herstellen. In der Regel empfiehlt es sich, Tools und andere Geschäftslogik auf deinem Anwendungsserver auszuführen. So bleibt diese Logik vertraulich und unabhängig vom Client.
Über einen separaten Steuerkanal, den „Sideband-Kanal“, kannst du Tool-Aufrufe, Geschäftslogik und weitere Implementierungsdetails auf dem Server schützen. Ein solcher Kanal steht inzwischen sowohl für SIP- als auch für WebRTC-Verbindungen zur Verfügung.
Mit einem Sideband-Kanal bestehen zwei aktive Verbindungen zur selben Realtime-Sitzung. Eine kommt vom Client der Person, die die Anwendung nutzt, die andere von deinem Anwendungsserver. Über die Serververbindung kannst du die Sitzung überwachen, Anweisungen aktualisieren und auf Tool-Aufrufe reagieren.
Mit WebRTC
- Wenn du eine Peer-Verbindung herstellst, rufst du von der Realtime API eine SDP-Antwort ab, mit der du die Verbindung konfigurierst. Wenn du den Beispielcode aus dem WebRTC-Leitfaden verwendest, sieht das etwa so aus.
const baseUrl = "https://api.openai.com/v1/realtime/calls";
const sdpResponse = await fetch(baseUrl, {
method: "POST",
body: offer.sdp,
headers: {
Authorization: `Bearer ${EPHEMERAL_KEY}`,
"Content-Type": "application/sdp",
},
});- Die Antwort auf die Fetch-Anfrage enthält im Header
Locationeine eindeutige Anruf-ID. Damit kann dein Server eine WebSocket-Verbindung zu derselben Realtime-Sitzung herstellen.
// Location: /v1/realtime/calls/rtc_123456
const location = sdpResponse.headers.get("Location");
const callId = location?.split("/").pop();
console.log(callId);- Auf dem Server kannst du dann wie bei einer üblichen WebSocket-Verbindung zur Realtime API auf Ereignisse lauschen und die Sitzung konfigurieren. Verwende dazu die Anruf-ID in der URL
wss://api.openai.com/v1/realtime?call_id=rtc_xxxxx, wie im folgenden Beispiel gezeigt.
import WebSocket from "ws";
const callId = "rtc_u1_9c6574da8b8a41a18da9308f4ad974ce";
// Connect to a WebSocket for the in-progress call
const url = "wss://api.openai.com/v1/realtime?call_id=" + callId;
const ws = new WebSocket(url, {
headers: {
Authorization: "Bearer " + process.env.OPENAI_API_KEY,
},
});
ws.on("open", function open() {
console.log("Connected to server.");
// Send client events over the WebSocket once connected
ws.send(
JSON.stringify({
type: "session.update",
session: {
type: "realtime",
instructions: "Be extra nice today!",
},
})
);
});
// Listen for and parse server events
ws.on("message", function incoming(message) {
console.log(JSON.parse(message.toString()));
});In Go übergibst du die Anruf-ID an die serverseitige Funktion, die deine Sitzung aktualisiert.
func updateSession(ctx context.Context, client openai.Client, callID string) error {
conn, err := client.Realtime.Connect(ctx, realtime.RealtimeConnectionOptions{}, option.WithQuery("call_id", callID))
if err != nil {
return err
}
defer conn.Close()
if err := conn.Send(ctx, realtime.RealtimeClientEventParamOfSessionUpdate(realtime.RealtimeSessionCreateRequestParam{
Instructions: openai.String("Be extra nice today!"),
})); err != nil {
return err
}
for {
event, err := conn.Recv(ctx)
if err != nil {
return err
}
if event.Type == "error" {
return fmt.Errorf("Realtime API error: %s", event.OfRealtimeErrorEvent.Error.Message)
}
if event.Type == "session.updated" {
if event.OfSessionUpdatedEvent.Session.OfRealtimeSessionCreateRequest.Instructions != "Be extra nice today!" {
return fmt.Errorf("session update was not applied")
}
fmt.Println("session.updated")
return nil
}
}
}So kannst du auf dem Server Tools hinzufügen, Sitzungen überwachen und Geschäftslogik ausführen, ohne diese Aktionen auf dem Client konfigurieren zu müssen.
Mit SIP
- Eine Person ruft OpenAI über eine SIP-Telefonverbindung an.
- OpenAI sendet einen Webhook an die Webhook-URL deines Anwendungsservers, um deine App über den Sitzungsstatus zu informieren. Der Webhook sieht etwa so aus.
POST https://my_website.com/webhook_endpoint
user-agent: OpenAI/1.0 (+https://platform.openai.com/docs/webhooks)
content-type: application/json
webhook-id: wh_685342e6c53c8190a1be43f081506c52 # unique id for idempotency
webhook-timestamp: 1750287078 # timestamp of delivery attempt
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4= # signature to verify authenticity from OpenAI
{
"object": "event",
"id": "evt_685343a1381c819085d44c354e1b330e",
"type": "realtime.call.incoming",
"created_at": 1750287018, // Unix timestamp
"data": {
"call_id": "some_unique_id",
"sip_headers": [
{ "name": "From", "value": "sip:+142555512112@sip.example.com" },
{ "name": "To", "value": "sip:+18005551212@sip.example.com" },
{ "name": "Call-ID", "value": "03782086-4ce9-44bf-8b0d-4e303d2cc590"}
]
}
}- Der Anwendungsserver öffnet eine WebSocket-Verbindung zur Realtime API. Dazu setzt er den Wert
call_idaus dem Webhook in eine URL wiewss://api.openai.com/v1/realtime?call_id={callId}ein. Die WebSocket-Verbindung bleibt für die Dauer des SIP-Anrufs bestehen.
Über die WebSocket-Verbindung kannst du anschließend Ereignisse senden und empfangen, um den Anruf zu steuern, genau wie bei einer Sitzung, die über WebSocket gestartet wurde. So kannst du den Anruf überwachen, Anweisungen während des Gesprächs aktualisieren und auf Tool-Aufrufe reagieren.