Telefonivõrk: SIP, LiveKit ja G.711
Sellel lehel
Uuendatud 3. novembril 2026, tuginedes xAI juhendile SIP Phone Calls, lehele Speech to Speech ja näitele Phone Voice Agent kokaraamatust. xAI võib vastata kõnedele otse sinu numbrile (otsene SIP, allkirjastatud veebikonks, suunamine, kõne lõpetamine, DTMF-klahvid), kasutades kas oma infrastruktuuri või silda läbi sinu serveri. Allikad: SIP Phone Calls · Speech to Speech · Phone Voice Agent.
Ühenda Voice Agent API telefonivõrguga
Voice Agent API suudab vastu võtta telefonikõnesid: sinu kliendid helistavad tavalisele numbrile ja suhtlevad sinu Grok-agendiga. Sinuni viib kolm teed, alates kõige integreeritumast kuni paindlikumani.
Tee 1: otsene SIP xAI-ga
Selles režiimis vastab kõnele xAI ise. Kõne jõuab xAI SIP-taristusse, mis teavitab sind veebikonksu kaudu; sinu rakendus liitub kõnega WebSocketi üle ja juhendab agenti.
- Registreeri number. Määra xAI-sse „otsene SIP“ (Direct SIP) number koos veebikonksu aadressiga, kuhu sissetulevad kõned saadetakse. Oma numbri kasutamisel määra
origin: "byo_trunk": xAI ei paku numbrite API kaudu. Vastus sisaldab allkirjastamise saladust, mida tagastatakse ainult üks kord, seega salvesta see oma saladuste hoidlasse. - Suuna oma operaator. Seadista oma sideoperaator või PBX saatma kõned aadressile
sip:{number}@sip.voice.x.ai. xAI aktsepteerib SIP-signaalimist TLS-i üle pordil 5061 või TCP/UDP üle pordil 5060; eelista;transport=tls, kui sinu operaator seda toetab. - Võta vastu veebikonks. Iga kõne kohta saadab xAI allkirjastatud
realtime.call.incomingveebikonksu. Kontrolli päiseidwebhook-id,webhook-timestampjawebhook-signature, kasutades allkirjastamise saladust, ja loe seejäreldata.call_id. - Liitu kõnega. Ava
wss://api.x.ai/v1/realtime?call_id={call_id}, kasutades oma API-võtit (ajutisi tokeneid SIP-seansi jaoks ei aktsepteerita), saadasession.updateja seejärelresponse.create, kui agent peaks rääkima hakkama.
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
Kui ühendus on loodud, käitub seanss nagu iga teine hääleseanss: xAI edastab helistaja heli ja esitab agendi vastuse, ilma et sinu server peaks heli töötlema.
Suunamine või kõne lõpetamine
Liini juhib kaks REST-kutset. POST /v1/realtime/calls/{call_id}/refer koos target_uri parameetriga vormis tel: või sip: suunab helistaja; päring ootab suunamise tulemust. 200 koos tühja kehaga tähendab, et sihtkoht vastas; 502 sisaldab SIP-tagasilükkamise koodi ja 504 annab märku ajapiirangu ületamisest. Pärast tõrget jääb seanss avatuks ja agent saab edasi rääkida: sinu ülesanne on lugeda vastust ja vajadusel lasta agendil juhtunut selgitada. POST /v1/realtime/calls/{call_id}/hangup lõpetab kõne.
Klaviatuurisisend (DTMF)
SIP-seansi ajal puhverdatakse helistaja vajutatud klahvid ja edastatakse need mudelile tekstina niipea, kui helistaja vajutab #, pärast 2,5-sekundilist pausi uue klahvita või niipea, kui ta rääkima hakkab. Sinu klient saab iga klahvi kohta ühe sündmuse input_audio_buffer.dtmf_event_received, nii et saad pidada arvestust. Et lasta agendil endal klahve vajutada (näiteks teise teenuse telefonimenüüs navigeerimiseks), lisa tema tööriistadele {"type": "function", "name": "send_dtmf"} ilma parameetriteta: API pakub skeemi ja saadab toonid ning sa ei tohi neid funktsioonikutseid ise käsitleda. Need sündmused eksisteerivad ainult SIP-seansis.
Toetatud operaatorid
xAI juhend kirjeldab seadistust neljale operaatorile (Twilio, kus on pagasiruumil lubatud Elastic SIP Trunking ja kõnede suunamine, kui suunad kõnesid; Bandwidth; Telnyx; ja Plivo) ning igale operaatorile, kontaktkeskusele või PBX-ile, mis suudab avada SIP-tee sinu numbri aadressile. Koodeki osas palutakse Telnyxi näites lubada vähemalt G.711 μ-law, G.711 A-law või G.722.
Tee 2: sild läbi sinu serveri
Kui soovid helivoogu ise kontrollida, võtab sinu server vastu kõneheli ja edastab selle tavalisele WebSocketi seansile. See on xAI kokaraamatu näite Phone Voice Agent arhitektuur: Twilio edastab kõneheli μ-law formaadis oma Media Streams’i kaudu ja server edastab selle API-le mõlemas suunas muundamata kujul.
# 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 aktsepteerib mõlemat G.711 varianti loomupäraselt, mis välistab ümberkodeerimise vajaduse: audio/pcmu (μ-law, Põhja-Ameerika ja Jaapani standard) ja audio/pcma (A-law, standard Euroopas ja enamikus teistes riikides), mõlemad sagedusel 8000 Hz.
{
"audio": {
"input": {"format": {"type": "audio/pcma", "rate": 8000}},
"output": {"format": {"type": "audio/pcma", "rate": 8000}}
}
}
DTMF-klahvid ning REST-kutsed suunamiseks ja kõne lõpetamiseks kuuluvad otsese SIP-tee juurde: silla kasutamisel haldab neid sinu operaator.
Tee 3: reaalaja raamistik
xAI dokumentatsioon loetleb kaks valmis integratsiooni: LiveKit Agents ja Pipecat. Need haldavad reaalaja transporti (WebRTC, ruumid, kõnede suunamine) ja ühendavad Grok hääleagendi õiges kohas, säästes meeskondi, kes ei soovi telefonikihti nullist ehitada.
Tootmises
Käsitle vaikhetki. Telefonis jätab vaikiv helistaja liini surnuks. turn_detection.idle_timeout_ms paneb agendi helistajaga ühendust võtma pärast sinu valitud pikkusega vaikhetke (tund 6).
Jätka vestlust uuel kõnel. Seansi taastamine toimib ka üle SIP-i: luba esimesel kõnel resumption.enabled ja säilita selle call_id. Kui klient uuesti helistab, ava wss://api.x.ai/v1/realtime?call_id={new_call_id}&conversation_id={previous_call_id} ja saada uuesti sama session.update. Ajalugu aegub pärast 30-minutilist tegevusetust.
Järgi reegleid. Teata helistajatele, et nad suhtlevad tehisintellektiga, ja kui salvestad kõnesid, ütle seda kohe alguses. Terviseandmete puhul märgib xAI, et pärast küsimustiku täitmist saab allkirjastada BAA (Business Associate Agreement) lepingu.
Mõõda latentsust. Helistaja tajutav viivitus koosneb telefonivõrgu, sinu silla (kui see on olemas) ja vastuse genereerimise ajast. Mõõda seda otsast otsani reaalsetel kõnedel ja hoia agendi poolt vestluse ajal kutsutavad funktsioonid kiirena.
Peamised punktid
- Otsese SIP-i korral vastab xAI sinu numbrile, teavitab sind allkirjastatud
realtime.call.incomingveebikonksuga ja sa liitud kõnega aadressilwss://api.x.ai/v1/realtime?call_id=… refersuunab kõne (tulemus jõuab tagasi HTTP-vastuses) jahanguplõpetab selle- DTMF-klahvid jõuavad mudelini ja logitakse sündmuse
input_audio_buffer.dtmf_event_receivedkaudu; tööriistsend_dtmfvõimaldab agendil klahve vajutada - Sillas läbi sinu serveri väldib loomupärane G.711 (
audio/pcmu,audio/pcma) ümberkodeerimist - LiveKit Agents ja Pipecat on integratsioonid, mida xAI loetleb