Telefonie: SIP, LiveKit en G.711
Op deze pagina
Bijgewerkt op 3 november 2026, gebaseerd op de xAI-gids SIP Phone Calls, de pagina Speech to Speech en het voorbeeld uit het kookboek Phone Voice Agent. xAI kan zelf gesprekken op uw nummer beantwoorden (directe SIP, ondertekende webhook, doorschakelen, ophangen, DTMF-toetsen), naast een brug via uw eigen server. Bronnen: SIP Phone Calls · Speech to Speech · Phone Voice Agent.
De Voice Agent API koppelen aan het telefoonnetwerk
De Voice Agent API kan telefoonoproepen afhandelen: uw klanten bellen een gewoon nummer en praten met uw Grok-agent. Drie routes leiden hiernaartoe, variërend van de meest geïntegreerde tot de meest flexibele.
Route 1: directe SIP met xAI
In deze modus beantwoordt xAI de oproep zelf. De oproep komt binnen op de SIP-infrastructuur van xAI, die u via een webhook op de hoogte stelt; uw applicatie voegt zich vervolgens via WebSocket bij het gesprek en stuurt de agent aan.
- Nummer registreren. Meld een “Direct SIP”-nummer aan bij xAI, samen met het webhook-adres waar binnenkomende oproepen naartoe worden gestuurd. Gebruik voor een nummer dat u zelf bezit
origin: "byo_trunk": xAI levert geen nummers via de API. Het antwoord bevat een ondertekeningssleutel (signing secret), die slechts één keer wordt teruggegeven; bewaar deze dus in uw kluis voor geheimen. - Carrier routeren. Stel uw carrier of PBX zo in dat oproepen worden doorgestuurd naar
sip:{number}@sip.voice.x.ai. xAI accepteert SIP-signalering over TLS op poort 5061, of TCP/UDP op poort 5060; geef de voorkeur aan;transport=tlswanneer uw carrier dit ondersteunt. - Webhook ontvangen. Voor elke oproep stuurt xAI een ondertekende
realtime.call.incoming-webhook. Verifieer de headerswebhook-id,webhook-timestampenwebhook-signaturemet de ondertekeningssleutel en lees vervolgensdata.call_id. - Gesprek joinen. Open
wss://api.x.ai/v1/realtime?call_id={call_id}met uw API-sleutel (tijdelijke tokens worden niet geaccepteerd voor een SIP-sessie), stuursession.updateen daarnaresponse.createwanneer de agent moet spreken.
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": "You are the customer service agent. Answer in English, briefly.",
"turn_detection": {"type": "server_vad"},
},
}))
await ws.send(json.dumps({"type": "response.create"})) # the agent greets the caller
async for message in ws:
event = json.loads(message)
# same handling as for a regular WebSocket session
Zodra de verbinding tot stand is gebracht, gedraagt de sessie zich als elke andere voicesessie: xAI geeft de audio van de beller door en laat de agent terugpraten, zonder dat uw server geluid hoeft te verwerken.
Doorschakelen of ophangen
Twee REST-aanroepen besturen de lijn. POST /v1/realtime/calls/{call_id}/refer, met een target_uri in de vorm tel: of sip:, schakelt de beller door; het verzoek wacht op de uitkomst van de doorschakeling. Een 200 met een lege body betekent dat de bestemming heeft opgenomen; een 502 bevat de SIP-weigeringscode en een 504 signaleert een time-out. Na een mislukking blijft de sessie open en kan de agent blijven praten: het is aan u om het antwoord te lezen en, indien nodig, de agent de hapering te laten uitleggen. POST /v1/realtime/calls/{call_id}/hangup beëindigt het gesprek.
Toetsinvoer (DTMF)
Bij een SIP-sessie worden de toetsen die de beller indrukt gebufferd en vervolgens als tekst naar het model gestuurd zodra de beller op # drukt, na 2,5 seconde zonder nieuwe toets, of zodra deze begint te spreken. Uw client ontvangt per toets één input_audio_buffer.dtmf_event_received-gebeurtenis, zodat u een logboek kunt bijhouden. Om de agent zelf toetsen te laten indrukken, bijvoorbeeld om door een telefoonmenu van een andere dienst te navigeren, voegt u {"type": "function", "name": "send_dtmf"} toe aan de tools, zonder parameters: de API levert het schema en verzendt de tonen, en u mag deze functieaanroepen niet zelf afhandelen. Deze gebeurtenissen bestaan alleen bij een SIP-sessie.
Gedocumenteerde carriers
De xAI-gids loopt de installatie door voor vier carriers (Twilio, met Elastic SIP Trunking en ingeschakelde oproepdoorschakeling op de trunk als u gesprekken doorschakelt; Bandwidth; Telnyx; en Plivo) en voor elke carrier, contactcenter of PBX die een SIP-route naar het adres van uw nummer kan openen. Wat de codec betreft, vraagt het Telnyx-voorbeeld om ten minste G.711 μ-law, G.711 A-law of G.722 in te schakelen.
Route 2: een brug via uw eigen server
Als u de controle over de audiostream wilt behouden, ontvangt uw server de oproepaudio en stuurt deze door naar een reguliere WebSocket-sessie. Dat is de architectuur van het voorbeeld Phone Voice Agent uit het xAI-kookboek: Twilio streamt de oproepaudio in μ-law via zijn Media Streams, en de server geeft deze ongewijzigd in beide richtingen door aan de API, zonder conversie.
# Phone call → carrier → your 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 at 8000 Hz, the North American phone network format
await ws.send(json.dumps({
"type": "session.update",
"session": {
"voice": "rex",
"instructions": "Customer service 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(),
}))
De API accepteert native beide G.711-varianten, wat transcoding overbodig maakt: audio/pcmu (μ-law, de standaard in Noord-Amerika en Japan) en audio/pcma (A-law, de standaard in Europa en de meeste andere landen), beide op 8000 Hz.
{
"audio": {
"input": {"format": {"type": "audio/pcma", "rate": 8000}},
"output": {"format": {"type": "audio/pcma", "rate": 8000}}
}
}
DTMF-toetsen en de REST-aanroepen voor doorschakelen en ophangen horen bij de directe SIP-route: bij een brug regelt uw carrier deze.
Route 3: een real-time framework
De xAI-documentatie noemt twee kant-en-klare integraties: LiveKit Agents en Pipecat. Deze verzorgen het real-time transport (WebRTC, rooms, oproeproutering) en koppelen de Grok-voice-agent op de juiste plek, wat een team dat geen telefonielag wil bouwen, veel werk bespaart.
In productie
Stiltes afhandelen. Aan de telefoon laat een beller die stilvalt een dode lijn achter. turn_detection.idle_timeout_ms zorgt ervoor dat de agent na een stilte van de door u gekozen duur contact opneemt met de beller (les 6).
Een gesprek oppakken bij een nieuwe oproep. Sessiehervatting werkt ook via SIP: schakel resumption.enabled in bij de eerste oproep en bewaar de bijbehorende call_id. Wanneer de klant terugbelt, opent u wss://api.x.ai/v1/realtime?call_id={new_call_id}&conversation_id={previous_call_id} en stuurt u opnieuw dezelfde session.update. De geschiedenis verloopt na 30 minuten inactiviteit.
Regels naleven. Vertel bellers dat ze met een AI praten en vermeld dit ook aan het begin als u gesprekken opneemt. Voor gezondheidsgegevens stelt xAI dat een BAA (Business Associate Agreement) kan worden getekend na het invullen van een vragenlijst.
Latentie meten. De vertraging die bellers ervaren, is de som van het telefoonnetwerk, uw brug (indien aanwezig) en de responsgeneratie. Meet dit end-to-end bij echte oproepen en zorg dat de functies die de agent tijdens het gesprek aanroept, snel zijn.
Belangrijkste punten
- Bij directe SIP beantwoordt xAI uw nummer, stelt u op de hoogte via een ondertekende
realtime.call.incoming-webhook en voegt u zich bij het gesprek viawss://api.x.ai/v1/realtime?call_id=… referschakelt de oproep door (de uitkomst komt terug in de HTTP-respons) enhangupbeëindigt deze- DTMF-toetsen bereiken het model en worden gelogd via
input_audio_buffer.dtmf_event_received; de toolsend_dtmflaat de agent toetsen indrukken - Bij een brug via uw server vermijdt native G.711 (
audio/pcmu,audio/pcma) transcoding - LiveKit Agents en Pipecat zijn de integraties die xAI vermeldt