Telefoni: SIP, LiveKit og G.711
På denne side
Opdateret 3. november 2026, baseret på xAI-guiden SIP Phone Calls, siden Speech to Speech og kogebogseksemplet Phone Voice Agent. xAI kan selv besvare opkald på dit nummer (direkte SIP, signeret webhook, overførsel, læg på, DTMF-taster) sideløbes med en bro gennem din egen server. Kilder: SIP Phone Calls · Speech to Speech · Phone Voice Agent.
Forbind Voice Agent API’et til telefonnettet
Voice Agent API’et kan modtage telefonopkald: Dine kunder ringer til et almindeligt nummer og taler med din Grok-agent. Tre veje fører dig dertil, fra den mest integrerede til den mest fleksible.
Vej 1: Direkte SIP med xAI
I denne tilstand besvarer xAI selv opkaldet. Opkaldet lander på xAI’s SIP-infrastruktur, som underretter dig via en webhook; din app forbinder sig til opkaldet over WebSocket og styrer agenten.
- Registrer nummeret. Deklar et „Direct SIP”-nummer hos xAI sammen med webhook-adressen, der skal modtage indgående opkald. Brug
origin: "byo_trunk"for et nummer, du selv ejer: xAI leverer ikke numre via API’et. Svaret indeholder en signeringsnøgle, der kun returneres én gang, så gem den i dit hemmelighedslager. - Diriger din operatør. Konfigurer din operatør eller PBX til at sende opkald til
sip:{number}@sip.voice.x.ai. xAI accepterer SIP-signalering over TLS på port 5061 eller TCP/UDP på port 5060; foretræk;transport=tls, når din operatør understøtter det. - Modtag webhooken. For hvert opkald sender xAI en signeret
realtime.call.incoming-webhook. Verificér headereenewebhook-id,webhook-timestampogwebhook-signaturemed signeringsnøglen, og læs derefterdata.call_id. - Deltag i opkaldet. Åbn
wss://api.x.ai/v1/realtime?call_id={call_id}med din API-nøgle (ephemeral tokens accepteres ikke til en SIP-session), sendsession.update, og derefterresponse.create, når agenten skal tale.
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
Når forbindelsen er etableret, opfører sessionen sig som enhver anden talesession: xAI videresender opkalderens lyd og afspiller agenten tilbage til dem, uden at din server behøver at håndtere selve lyden.
Overførsel eller læg på
To REST-kald styrer linjen. POST /v1/realtime/calls/{call_id}/refer med en target_uri i formatet tel: eller sip: overfører opkalderen; forespørgslen venter på resultatet af overførslen. En 200 med en tom body betyder, at destinationen svarede; en 502 indeholder SIP-afvisningskoden, og en 504 signalerer et timeout. Efter en fejl forbliver sessionen åben, og agenten kan fortsætte med at tale: Det er op til dig at læse svaret og om nødvendigt få agenten til at forklare problemet. POST /v1/realtime/calls/{call_id}/hangup afslutter opkaldet.
Tastaturinput (DTMF)
I en SIP-session bufferes de taster, opkalderen trykker på, og sendes derefter til modellen som tekst, så snart opkalderen trykker på #, efter 2,5 sekunder uden nyt tastetryk, eller så snart de begynder at tale. Din klient modtager én input_audio_buffer.dtmf_event_received-begivenhed pr. tast, så du kan føre en log. For at lade agenten selv trykke på taster, f.eks. for at navigere i en anden tjenestes telefonmenu, skal du tilføje {"type": "function", "name": "send_dtmf"} til dens værktøjer uden parametre: API’et leverer skemaet og sender tonerne, og du må ikke besvare disse funktionskald. Disse begivenheder eksisterer kun i en SIP-session.
Dokumenterede operatører
xAI-guiden gennemgår opsætningen for fire operatører (Twilio med Elastic SIP Trunking og aktiveret opkaldsoverførsel på trunken, hvis du overfører opkald; Bandwidth; Telnyx; og Plivo) samt for enhver operatør, kontaktcenter eller PBX, der kan åbne en SIP-rute til dit nummers adresse. På codec-siden beder Telnyx-eksemplet dig om at aktivere mindst G.711 μ-law, G.711 A-law eller G.722.
Vej 2: En bro gennem din egen server
Hvis du vil beholde kontrollen over lydstrømmen, modtager din server opkaldslyden og videresender den til en almindelig WebSocket-session. Det er arkitekturen i xAI-kogebogens eksempel Phone Voice Agent: Twilio streamer opkaldslyden i μ-law gennem sine Media Streams, og serveren sender den videre til API’et, som den er, uden konvertering i begge retninger.
# 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(),
}))
API’et accepterer nativt begge G.711-varianter, hvilket undgår enhver transkodning: audio/pcmu (μ-law, standarden i Nordamerika og Japan) og audio/pcma (A-law, standarden i Europa og de fleste andre lande), begge ved 8000 Hz.
{
"audio": {
"input": {"format": {"type": "audio/pcma", "rate": 8000}},
"output": {"format": {"type": "audio/pcma", "rate": 8000}}
}
}
DTMF-taster samt REST-kald til overførsel og afslutning hører til den direkte SIP-vej: I en bro-håndtering håndterer din operatør disse.
Vej 3: Et realtidsframework
xAI-dokumentationen lister to færdige integrationer: LiveKit Agents og Pipecat. De håndterer realtidstransport (WebRTC, rum, opkaldsrouting) og kobler Grok-voice-agenten ind på det rette sted, hvilket sparer et team, der ikke ønsker at bygge et telefonilag fra bunden, for arbejdet.
I produktion
Håndter stilhed. På telefonen efterlader en opkalder, der tier, en død linje. turn_detection.idle_timeout_ms får agenten til at tjekke ind hos opkalderen efter en stilhed af den længde, du vælger (lektion 6).
Genoptag en samtale ved et nyt opkald. Sessionsgenoptagelse fungerer også over SIP: Aktivér resumption.enabled ved det første opkald, og behold dets call_id. Når kunden ringer tilbage, åbnes wss://api.x.ai/v1/realtime?call_id={new_call_id}&conversation_id={previous_call_id}, og du sender den samme session.update igen. Historikken udløber efter 30 minutters inaktivitet.
Følg reglerne. Fortæl opkaldere, at de taler med en AI, og sig det også i starten, hvis du optager opkald. For sundhedsdata oplyser xAI, at en BAA (Business Associate Agreement) kan underskrives efter et spørgeskema.
Mål din latency. Forsinkelsen, som opkaldere oplever, er summen af telefonnettet, din bro (hvis du har en) og svar-genereringen. Mål den ende-til-ende på rigtige opkald, og sørg for, at de funktioner, agenten kalder under samtalen, er hurtige.
Vigtige pointer
- Med direkte SIP besvarer xAI dit nummer, underretter dig med en signeret
realtime.call.incoming-webhook, og du deltager i opkaldet viawss://api.x.ai/v1/realtime?call_id=… referoverfører opkaldet (resultatet returneres i HTTP-svaret), oghangupafslutter det- DTMF-taster når modellen og logges via
input_audio_buffer.dtmf_event_received; værktøjetsend_dtmflader agenten trykke på taster - I en bro gennem din server undgår native G.711 (
audio/pcmu,audio/pcma) transkodning - LiveKit Agents og Pipecat er de integrationer, xAI lister