Telefonie: SIP, LiveKit und G.711
Auf dieser Seite
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.
- 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. - Routen Sie Ihren Anbieter. Konfigurieren Sie Ihren Anbieter oder Ihre PBX, um Anrufe an
sip:{number}@sip.voice.x.aizu 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. - Empfangen Sie den Webhook. Für jeden Anruf sendet xAI einen signierten
realtime.call.incoming-Webhook. Verifizieren Sie die Headerwebhook-id,webhook-timestampundwebhook-signaturemit dem Signiergeheimnis, und lesen Sie danndata.call_id. - 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 Siesession.update, und dannresponse.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 überwss://api.x.ai/v1/realtime?call_id=…an. referleitet den Anruf weiter (das Ergebnis kommt im HTTP-Antwortkörper zurück), undhangupbeendet ihn.- DTMF-Tasten erreichen das Modell und werden über
input_audio_buffer.dtmf_event_receivedprotokolliert; das Toolsend_dtmfermö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.