Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Telefonie und SIP

Verbinde Telefonanrufe über SIP mit OpenAI.

Wähle deine API aus, um zu sehen, wie du die Verbindung herstellst und welche Sitzungsereignisse du erhältst.

Verbinde eingehende und ausgehende Anrufe über einen SIP-Trunk mit GPT-Live. Dein Anbieter tauscht die Audiodaten des Anrufs mit OpenAI aus. Dein Backend konfiguriert die Sitzung, steuert den Anruf und führt die Geschäftslogik aus. Die SIP-Signalisierung erfolgt über TLS. Für die Audiodaten setzt GPT-Live SRTP voraus.

  • Eingehenden Anruf verarbeiten: Dein Backend empfängt einen Webhook für den eingehenden Anruf und nimmt den Anruf anschließend an oder lehnt ihn ab.
  • Ausgehenden Anruf starten: Erstelle eine Sitzung, um über deinen Anbieter eine Telefonnummer anzurufen. Dafür brauchst du weder einen Webhook für eingehende Anrufe noch eine Anfrage zur Anrufannahme.

Nutze eine Sideband-Verbindung, wenn dein Backend Sitzungsereignisse empfangen oder Befehle senden muss. Sie verbindet dein Backend mit dem laufenden Gespräch. Die Audiodaten laufen weiter über SIP. Weise jeder Aktion genau einen Handler zu. So werden Tools auch dann nur einmal ausgeführt, wenn ein Webhook mehrfach zugestellt wird oder dasselbe Ereignis auf mehreren Verbindungen eingeht.

Eingehenden Anruf verarbeiten

Leite eingehende Anrufe von deinem SIP-Anbieter an dein OpenAI-Projekt weiter. Dein Backend empfängt einen Webhook und entscheidet für jeden Anruf, ob es ihn annimmt.

Telefonnummer und SIP-Trunk konfigurieren

Nutze einen SIP-Trunking-Anbieter wie Twilio, um eine Telefonnummer mit GPT-Live zu verbinden. Nachdem du bei deinem Anbieter eine Nummer gekauft hast, führe die folgenden Schritte aus.

  1. Öffne dein Projekt in den OpenAI-Einstellungen. Erstelle unter Webhooks einen Webhook-Endpunkt und abonniere für diesen Endpunkt das Ereignis live.transport.incoming.
  2. Die Projekt-ID findest du unter Allgemein. Sie beginnt mit proj_. Verwende die ID des Projekts, zu dem der Webhook gehört.
  3. Lege den globalen SIP-URI sip:$PROJECT_ID@sip.api.openai.com;transport=tls als Ziel für den SIP-Trunk deines Anbieters fest oder wähle einen der folgenden regionalen Endpunkte.
    • Für Datenresidenz in Europa verwende sip:$PROJECT_ID@sip-eu.api.openai.com;transport=tls.
    • Für SIP-Hosts mit physischem Standort in Indien verwende sip:$PROJECT_ID@sip-in.api.openai.com;transport=tls.

Prüfe vorab, ob die SIP-Unterstützung für GPT-Live in deinem Projekt aktiviert ist und der SIP-Trunk deines Anbieters Anrufe an dieses Projekt leitet.

Eingehenden Anruf empfangen

Wenn OpenAI einen Anruf für dein Projekt empfängt, sendet OpenAI ein live.transport.incoming-Ereignis an deinen Webhook-Endpunkt. Prüfe die Webhook-Signatur und filtere doppelte Zustellungen heraus. Nimm den Anruf anschließend an oder lehne ihn ab.

Der Webhook kennzeichnet einen SIP-Anruf mit data.type: "sip" und liefert data.session_id. Verwende diese Sitzungs-ID unverändert für jede Anrufaktion in der Live API. Behandle data.sip_headers als nicht vertrauenswürdige Metadaten der anrufenden Person. Verwende sie nicht zur Autorisierung.

Der Webhook-Body kann beispielsweise so aussehen:

{
  "object": "event",
  "id": "evt_abc123",
  "type": "live.transport.incoming",
  "created_at": 1750287018,
  "data": {
    "type": "sip",
    "session_id": "live_123",
    "sip_headers": [
      { "name": "From", "value": "sip:+14155550123@sip.example.com" },
      { "name": "To", "value": "sip:+18005550100@sip.example.com" },
      { "name": "Call-ID", "value": "call-123@example.com" }
    ]
  }
}

Das Feld created_at enthält einen Unix-Zeitstempel in Sekunden. Bei der Zustellung erhältst du unter anderem die Header webhook-id zum Erkennen von Duplikaten, webhook-timestamp für den Zeitpunkt des Zustellversuchs und webhook-signature zur Signaturprüfung. Die Beispiele zur Prüfung von Webhook-Signaturen zeigen, wie du serverseitige Handler dafür implementierst.

Bestehende Integrationen können weiterhin das veraltete Ereignis live.call.incoming empfangen, das kein Feld data.type enthält. Verarbeite während der Migration beide Ereignisnamen und behalte das alte Abonnement bei, bis alle ausstehenden Zustellungen und Wiederholungsversuche für das alte Ereignis abgeschlossen sind. Für denselben ausstehenden Anruf kann auch ein Realtime-Webhook ausgelöst werden. Lass genau einen Handler über die Annahme oder Ablehnung entscheiden, damit der Anruf nicht über beide APIs angenommen wird.

Anruf annehmen oder ablehnen

Wende die Autorisierungs- und Routingregeln deiner Anwendung an. Um den Anruf anzunehmen, sende eine authentifizierte Anfrage an POST /v1/live/sessions/{session_id}/accept mit einem session-Objekt auf der obersten Ebene.

{
  "session": {
    "type": "live",
    "model": "gpt-live-1",
    "instructions": "You are answering an inbound support call.",
    "audio": { "output": { "voice": "marin" } },
    "delegation": { "type": "client" }
  }
}

Sende Anfragen zur Anrufsteuerung von deinem vertrauenswürdigen Backend aus mit Authorization: Bearer $OPENAI_API_KEY. Lege Stimme und Delegationsmodus bei der Annahme fest. Lass audio.format weg, da SIP das Audioformat aushandelt. Das Beispiel delegiert Aufgaben an den Client. Dein Backend muss diese Aufgaben ausführen. Die Konfigurationen für den Client und für Responses findest du im Leitfaden Delegation und Tools.

Bei erfolgreicher Annahme erhältst du nach der Initialisierung der Sitzung 200 OK mit leerem Antwortbody. Behandle HTTP-Fehler, bevor du den Anruf als angenommen einstufst.

Um den Anruf abzulehnen, sende POST /v1/live/sessions/{session_id}/reject mit einem SIP-Statuscode, zum Beispiel { "status_code": 486 } für „besetzt“. Der Statuscode muss eine ganze Zahl von 300 bis einschließlich 699 sein. Die erste Entscheidung über Annahme oder Ablehnung gilt. Bei einem weiteren Entscheidungsversuch erhältst du decision_already_made.

Backend anbinden

Stelle nach der Annahme eine Sideband-WebSocket-Verbindung zu wss://api.openai.com/v1/live/sessions/{session_id}/attach her. Verwende die Sitzungs-ID des angenommenen Anrufs sowie dieselben Authentifizierungsdaten für das Projekt und dieselben Verbindungsheader. Sende session.start nicht erneut.

SIP überträgt die Audiodaten des Anrufs. Nutze die Sideband-Verbindung für Transkripte, Delegation, Tools, Befehle und gespiegelte Audiodaten. Lege für jeden Seiteneffekt genau eine zuständige Komponente fest, auch wenn mehrere Verbindungen dasselbe Ereignis empfangen.

Sobald die Verbindung steht, kannst du über die Anrufsteuerung Tastentöne senden, den Anruf weiterleiten oder auflegen.

Ausgehenden Anruf starten

Rufe mit Sitzung erstellen über deinen SIP-Anbieter eine Telefonnummer an. Dein Anbieter stellt die Verbindung zum Telefonnetz her. GPT-Live führt das Gespräch.

Alle Organisationen können ausgehende SIP-Anrufe über die Live API starten. Der Endpunkt der Realtime API zum Erstellen von Anrufen unterstützt diese Funktion nicht.

SIP-Trunk konfigurieren

Verwende einen Trunk, der TLS für die Signalisierung und SDES-SRTP für die Medienübertragung unterstützt. Aktiviere SRTP in den Einstellungen deines Anbieters, bevor du einen Anruf startest.

Sende die Trunk-Konfiguration bei jeder Anfrage mit.

Feld Wert
transport.destination Die anzurufende Telefonnummer im E.164-Format, zum Beispiel +14155550123. SIP-URIs werden als Ziel nicht unterstützt.
transport.trunk.provider_url Ein Endpunkt deines Anbieters, zum Beispiel sips:sip.example.com:5061. Der Standardport ist 5061. Die Angabe ;transport=tcp ist optional.
transport.trunk.auth.type digest für die SIP-Digest-Authentifizierung.
transport.trunk.auth.username Dein SIP-Benutzername beim Anbieter.
transport.trunk.auth.password Dein SIP-Passwort beim Anbieter.
transport.trunk.caller_number Die Absenderrufnummer im E.164-Format, die an deinen Anbieter übermittelt wird.

Der Endpunkt deines Anbieters muss für die TLS-Signalisierung sips: verwenden. Die URL darf keine Zugangsdaten, Pfade, URI-Header oder sonstigen URI-Parameter enthalten. Lokale Hostnamen und direkt angegebene private oder lokale IP-Adressen werden abgelehnt. Bewahre deinen OpenAI-API-Schlüssel und deine SIP-Zugangsdaten auf deinem Server auf.

Sitzung erstellen

Sende POST /v1/live/sessions mit deiner Sitzungskonfiguration und transport.type: "sip". Lege Stimme und Delegationsmodus beim Erstellen der Sitzung fest. Lass audio.format weg, da SIP das Audioformat aushandelt.

Dieses Beispiel verwendet curl und jq. Setze OPENAI_API_KEY, SIP_USERNAME und SIP_PASSWORD in deiner Serverumgebung. Ersetze den Endpunkt des Anbieters und die Telefonnummern im Beispiel durch deine eigenen Werte. Das Beispiel delegiert Aufgaben an den Client. Dein Backend muss die delegierten Aufgaben ausführen.

jq -n \
  --arg username "$SIP_USERNAME" \
  --arg password "$SIP_PASSWORD" \
  '{
    "session": {
      "model": "gpt-live-1",
      "instructions": "Help the user schedule an appointment.",
      "audio": { "output": { "voice": "marin" } },
      "delegation": { "type": "client" }
    },
    "transport": {
      "type": "sip",
      "destination": "+14155550123",
      "trunk": {
        "provider_url": "sips:sip.example.com:5061",
        "auth": {
          "type": "digest",
          "username": $username,
          "password": $password
        },
        "caller_number": "+14155550100"
      }
    }
  }' | curl https://api.openai.com/v1/live/sessions \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -H "Content-Type: application/json" \
    --data-binary @-

Nach der Initialisierung der Sitzung erhältst du auf die Anfrage 200 OK mit folgendem Inhalt.

{
  "session": { "id": "live_123" },
  "transport": { "type": "sip" }
}

Diese Antwort sagt noch nichts darüber aus, ob jemand den Anruf angenommen hat. Sie enthält weder SDP-Daten noch Zugangsdaten für den Trunk. Verwende session.id unverändert für die Sideband-Verbindung und die Anrufsteuerung. Für einen ausgehenden Anruf brauchst du weder einen Webhook für eingehende Anrufe noch eine Anfrage zur Anrufannahme.

Anruf überwachen und beenden

Verbinde dein Backend über wss://api.openai.com/v1/live/sessions/{session_id}/attach mit der Sitzung. Verwende dafür deinen OpenAI-API-Schlüssel. Sende session.start nicht erneut. Über die Sideband-Verbindung erhältst du Gesprächsereignisse, delegierte Aufgaben und Meldungen zum Anrufstatus. SIP überträgt die Audiodaten.

Ereignis Bedeutung
transport.ringing Der Anbieter meldet, dass es klingelt oder bereits vor der Annahme Mediendaten übertragen werden (Early Media).
transport.answered Der Anruf wurde angenommen und die Medienverbindung steht.
transport.failed Der Anrufaufbau ist nach der Initialisierung der Sitzung fehlgeschlagen. Prüfe error.code und error.message.

Jedes Ereignis zum Anrufstatus enthält event_id und session_id. Stelle die Sideband-Verbindung sofort nach dem Erstellen der Sitzung her. Über diese Verbindung erhältst du zuerst die Ereignisse aus den 3 Sekunden unmittelbar vor dem Verbindungsaufbau erneut und anschließend neue Ereignisse. Verbindest du dich später, können dir frühere Statusmeldungen entgehen. Dieses Zeitfenster gilt auch für die erneute Übertragung von Gesprächsereignissen und gespiegelten Audiodaten. Erneut zugestellte Ereignisse zum Anrufstatus behalten ihre ursprüngliche Ereignis-ID. Filtere Duplikate anhand von event_id heraus. Einzelheiten findest du im Abschnitt Erneute Übertragung beim Verbindungsaufbau.

Sobald die Verbindung steht, kannst du über die Anrufsteuerung Tastentöne senden, den Anruf weiterleiten oder auflegen. Halte die Sideband-Verbindung offen, um session.closed und die endgültigen Nutzungsdaten zu empfangen. Einzelheiten findest du im Abschnitt Nutzung erfassen und Sitzung geordnet beenden.

Grenzwerte beachten und Fehler behandeln

Das Telefon klingelt höchstens 3 Minuten lang. Nach der Annahme kann ein Anruf höchstens 2 Stunden dauern. Diese Grenzwerte lassen sich in der Anfrage zum Erstellen der Sitzung nicht ändern.

Ist die Sitzungskonfiguration ungültig, meldet die API den Fehler direkt in der Antwort auf die Erstellungsanfrage. Schlägt der Aufbau der Transportverbindung fehl, kann die API 502 zurückgeben. Bei einer Zeitüberschreitung während der Initialisierung erhältst du 504. Achte nach erfolgreicher Erstellung auf transport.failed, um asynchrone Fehler beim Verbindungsaufbau zu erkennen.

Laufenden Anruf steuern

Mit diesen Funktionen kannst du sowohl eingehende als auch ausgehende SIP-Anrufe steuern.

Tastenereignisse senden und empfangen

Wenn die anrufende Person eine Taste drückt, empfängst du über die Sideband-Verbindung transport.dtmf.received. Um einen DTMF-Ton an den SIP-Trunk zu senden, sende das Client-Ereignis transport.dtmf.send über den Sideband-WebSocket. Nach erfolgreicher Übertragung des Tons empfängst du über die Sideband-Verbindung transport.dtmf.sent.

Wenn du eine event_id angibst, enthält die Benachrichtigung diese ID als client_event_id. Bei einem Fehler erhältst du ein error-Ereignis mit error.client_event_id.

Anruf weiterleiten oder beenden

Um den Anruf weiterzuleiten, sende POST /v1/live/sessions/{session_id}/refer und gib das Ziel mit { "target_uri": "sip:agent@example.com" } an. Um aufzulegen, sende POST /v1/live/sessions/{session_id}/hangup ohne Anfragebody. Bei Erfolg geben beide Endpunkte 200 OK mit leerem Antwortbody zurück.

Das Weiterleitungsziel wird in den SIP-Header Refer-To übernommen. Als Ziel kannst du einen Telefon-URI wie tel:+14155550123 oder einen SIP-URI wie sip:agent@example.com angeben. Dein Anbieter führt die weiteren Schritte der Weiterleitung aus.

Halte die Sideband-Verbindung offen, bis session.closed die endgültigen Nutzungsdaten liefert. Weitere Informationen zu den Nutzungsdaten und den Gründen für das Sitzungsende findest du im Abschnitt Nutzung erfassen und Sitzung geordnet beenden.

Netzwerkanforderungen für SIP

SIP-Anrufe über GPT-Live nutzen getrennte Netzwerkpfade für die Signalisierung und die Medienübertragung. Konfiguriere dein Netzwerk so, dass es beide Arten von Datenverkehr zulässt.

  • SIP-Signalisierung: sip.api.openai.com und sip-eu.api.openai.com sind Endpunkte mit GeoIP-Routing. Der Endpunkt sip-in.api.openai.com leitet den SIP-Verkehr an SIP-Hosts in Indien weiter. Erlaube ausgehenden TCP/TLS-Verkehr zu den Adressen, die DNS für den gewählten Endpunkt zurückgibt. Verwende dafür Port 5061.
  • Medienübertragung mit SRTP: Die API gibt im ausgehandelten SDP eine separate IP-Adresse und einen UDP-Port für die Medienübertragung an. Erlaube SRTP-Verkehr über UDP in beide Richtungen für die folgenden CIDR-Blöcke:
    • 13.79.45.80/28
    • 20.204.17.112/28
    • 23.98.140.64/28
    • 40.67.149.176/28
    • 40.83.204.240/28

Nächste Schritte mit GPT-Live