Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Telefonie: SIP, LiveKit und G.711

Lektion 15 von 16 Aktualisiert am 3. November 2026 Entwickler
Auf dieser Seite
  1. Verbindung der Voice-Agent-API mit dem Telefonnetz
  2. Weg 1: direktes SIP mit xAI
  3. Weg 2: eine Brücke über Ihren eigenen Server
  4. Weg 3: ein Echtzeit-Framework
  5. In der Produktion
  6. Kernaussagen

Aktualisiert am 3. November 2026, basierend auf dem xAI-Leitfaden zu SIP-Telefonaten, der Seite Speech to Speech und dem Kochbuch-Beispiel für Phone Voice Agent. xAI kann Anrufe direkt auf Ihrer Nummer beantworten (direktes SIP, signierter Webhook, Weiterleitung, Hängenlegen, DTMF-Tasten), sowie über eine Brücke durch Ihren eigenen Server. Quellen: SIP-Telefonate · Speech to Speech · Phone Voice Agent.

Verbindung der Voice-Agent-API mit dem Telefonnetz

Die Voice-Agent-API kann Telefonate empfangen: Ihre Kunden wählen eine gewöhnliche Nummer und sprechen mit Ihrem Grok-Agenten. Drei Wege führen dorthin, vom am stärksten integrierten bis zum flexibelsten.

Weg 1: direktes SIP mit xAI

In diesem Modus beantwortet xAI den Anruf selbst. Der Anruf landet auf der SIP-Infrastruktur von xAI, die Sie per Webhook benachrichtigt; Ihre Anwendung schließt sich über WebSocket dem Anruf an und steuert den Agenten.

  1. Registrieren Sie die Nummer. Erklären Sie bei xAI eine „Direct SIP”-Nummer zusammen mit der Webhook-Adresse, die eingehende Anrufe empfangen soll. Für eine Nummer, die Sie besitzen, verwenden Sie origin: "byo_trunk": xAI stellt keine Nummern über die API bereit. Die Antwort enthält ein Signiergeheimnis, das nur einmal zurückgegeben wird; speichern Sie es in Ihrem Geheimnis-Safe.
  2. Routen Sie Ihren Anbieter. Konfigurieren Sie Ihren Anbieter oder Ihre PBX, um Anrufe an sip:{number}@sip.voice.x.ai zu senden. xAI akzeptiert SIP-Signalisierung über TLS auf Port 5061 oder TCP/UDP auf Port 5060; bevorzugen Sie ;transport=tls, wenn Ihr Anbieter dies unterstützt.
  3. Empfangen Sie den Webhook. Für jeden Anruf sendet xAI einen signierten realtime.call.incoming-Webhook. Verifizieren Sie die Header webhook-id, webhook-timestamp und webhook-signature mit dem Signiergeheimnis, und lesen Sie dann data.call_id.
  4. Schließen Sie sich dem Anruf an. Öffnen Sie wss://api.x.ai/v1/realtime?call_id={call_id} mit Ihrem API-Schlüssel (ephemere Tokens werden für eine SIP-Sitzung nicht akzeptiert), senden Sie session.update, und dann response.create, wenn der Agent sprechen soll.
import json
import os

import websockets


async def join_call(call_id):
    async with websockets.connect(
        f"wss://api.x.ai/v1/realtime?call_id={call_id}",
        additional_headers={"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"},
    ) as ws:
        await ws.send(json.dumps({
            "type": "session.update",
            "session": {
                "voice": "rex",
                "instructions": "Sie sind der Kundenservice-Agent. Antworten Sie auf Englisch und kurz.",
                "turn_detection": {"type": "server_vad"},
            },
        }))
        await ws.send(json.dumps({"type": "response.create"}))  # der Agent begrüßt den Anrufer

        async for message in ws:
            event = json.loads(message)
            # gleiche Verarbeitung wie für eine reguläre WebSocket-Sitzung

Sobald verbunden, verhält sich die Sitzung wie jede andere Voice-Sitzung: xAI leitet die Audioaufnahme des Anrufers weiter und spielt den Agenten für diesen ab, ohne dass Ihr Server Tondaten transportiert.

Weiterleitung oder Hängenlegen

Zwei REST-Aufrufe steuern die Leitung. POST /v1/realtime/calls/{call_id}/refer mit einem target_uri im Format tel: oder sip: leitet den Anrufer weiter; die Anfrage wartet auf das Ergebnis der Weiterleitung. Ein 200 mit leerem Körper bedeutet, dass das Ziel geantwortet hat; ein 502 enthält den SIP-Ablehnungscode, und ein 504 signalisiert ein Timeout. Nach einem Fehler bleibt die Sitzung offen und der Agent kann weiterreden: Es liegt an Ihnen, die Antwort zu lesen und ggf. den Agenten auffordern, den Hänger zu erklären. POST /v1/realtime/calls/{call_id}/hangup beendet den Anruf.

Tastatureingabe (DTMF)

In einer SIP-Sitzung werden die Tasten, die der Anrufer drückt, gepuffert und dann als Text an das Modell übermittelt, sobald der Anrufer # drückt, nach 2,5 Sekunden ohne neue Taste oder sobald er spricht. Ihr Client erhält für jede Taste ein einzelnes input_audio_buffer.dtmf_event_received-Ereignis, sodass Sie eine Aufzeichnung führen können. Um zu ermöglichen, dass der Agent selbst Tasten drückt, z. B. um das Telefonmenü eines anderen Dienstes zu navigieren, fügen Sie {"type": "function", "name": "send_dtmf"} zu seinen Tools hinzu, ohne Parameter: Die API stellt das Schema bereit und sendet die Töne, und Sie dürfen diese Funktionsaufrufe nicht beantworten. Diese Ereignisse existieren nur in einer SIP-Sitzung.

Dokumentierte Anbieter

Der xAI-Leitfaden beschreibt die Einrichtung für vier Anbieter (Twilio, mit Elastic SIP Trunking und aktiver Weiterleitung auf dem Trunk, falls Sie Anrufe weiterleiten; Bandwidth; Telnyx; und Plivo) sowie für jeden Anbieter, Call-Center oder PBX, der eine SIP-Route zu Ihrer Nummernadresse öffnen kann. Auf der Codec-Seite fordert das Telnyx-Beispiel Sie auf, mindestens G.711 μ-law, G.711 A-law oder G.722 zu aktivieren.

Weg 2: eine Brücke über Ihren eigenen Server

Wenn Sie die Kontrolle über den Audio-Stream behalten möchten, empfängt Ihr Server das Anrufaudio und leitet es an eine reguläre WebSocket-Sitzung weiter. Das ist die Architektur des xAI-Kochbuch-Beispiels Phone Voice Agent: Twilio streamt das Anrufaudio im μ-law-Format über seine Media Streams, und der Server leitet es in beide Richtungen unverändert an die API weiter.

# Telefonat → Anbieter → Ihr Server → xAI WebSocket
import base64
import json
import os

import websockets


async def relay_call(call_audio_stream):
    ws = await websockets.connect(
        "wss://api.x.ai/v1/realtime?model=grok-voice-latest",
        additional_headers={"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"},
    )

    # G.711 μ-law bei 8000 Hz, das Format des nordamerikanischen Telefonnetzes
    await ws.send(json.dumps({
        "type": "session.update",
        "session": {
            "voice": "rex",
            "instructions": "Kundenservice-Agent.",
            "turn_detection": {"type": "server_vad"},
            "audio": {
                "input": {"format": {"type": "audio/pcmu", "rate": 8000}},
                "output": {"format": {"type": "audio/pcmu", "rate": 8000}},
            },
        },
    }))

    async for chunk in call_audio_stream:
        await ws.send(json.dumps({
            "type": "input_audio_buffer.append",
            "audio": base64.b64encode(chunk).decode(),
        }))

Die API akzeptiert beide G.711-Varianten nativ, was jegliches Transcoding vermeidet: audio/pcmu (μ-law, der Standard in Nordamerika und Japan) und audio/pcma (A-law, der Standard in Europa und den meisten anderen Ländern), beide bei 8000 Hz.

{
  "audio": {
    "input": {"format": {"type": "audio/pcma", "rate": 8000}},
    "output": {"format": {"type": "audio/pcma", "rate": 8000}}
  }
}

DTMF-Tasten und die REST-Aufrufe zur Weiterleitung und zum Hängenlegen gehören zum direkten SIP-Pfad: In einer Brücke übernimmt Ihr Anbieter diese Aufgaben.

Weg 3: ein Echtzeit-Framework

Die xAI-Dokumentation listet zwei fertige Integrationen auf: LiveKit Agents und Pipecat. Diese übernehmen den Echtzeit-Transport (WebRTC, Räume, Anruf-Verwaltung) und stecken den Grok-Voice-Agenten an der richtigen Stelle ein, was einem Team, das keine Telefonie-Schicht selbst bauen möchte, diese Arbeit erspart.

In der Produktion

Handhaben Sie Stille. Am Telefon hinterlässt ein schweigender Anrufer eine tote Leitung. turn_detection.idle_timeout_ms lässt den Agenten nach einer Stille der von Ihnen gewählten Länge mit dem Anrufer nachhaken (Lektion 6).

Nehmen Sie ein Gespräch in einem neuen Anruf auf. Sitzungsfortsetzung funktioniert auch über SIP: Aktivieren Sie resumption.enabled beim ersten Anruf und behalten Sie dessen call_id. Wenn der Kunde zurückruft, öffnen Sie wss://api.x.ai/v1/realtime?call_id={new_call_id}&conversation_id={previous_call_id} und senden Sie dasselbe session.update erneut. Die Historie verfällt nach 30 Minuten Inaktivität.

Befolgen Sie die Regeln. Sagen Sie Anrufern, dass sie mit einer KI sprechen, und sagen Sie bei Aufzeichnungen dies zu Beginn. Für Gesundheitsdaten sagt xAI, ein BAA (Business Associate Agreement) könne nach einem Fragebogen unterzeichnet werden.

Messen Sie Ihre Latenz. Die Verzögerung, die Anrufer wahrnehmen, addiert sich aus dem Telefonnetz, Ihrer Brücke (falls vorhanden) und der Antwortgenerierung. Messen Sie sie von Ende zu Ende an echten Anrufen und halten Sie die Funktionen, die der Agent während des Gesprächs aufruft, schnell.

Kernaussagen

  • Mit direktem SIP beantwortet xAI Ihre Nummer, benachrichtigt Sie mit einem signierten realtime.call.incoming-Webhook, und Sie schließen sich dem Anruf über wss://api.x.ai/v1/realtime?call_id=… an.
  • refer leitet den Anruf weiter (das Ergebnis kommt im HTTP-Antwortkörper zurück), und hangup beendet ihn.
  • DTMF-Tasten erreichen das Modell und werden über input_audio_buffer.dtmf_event_received protokolliert; das Tool send_dtmf ermöglicht es dem Agenten, Tasten zu drücken.
  • In einer Brücke über Ihren Server vermeidet natives G.711 (audio/pcmu, audio/pcma) Transcoding.
  • LiveKit Agents und Pipecat sind die Integrationen, die xAI auflistet.