Telefonija: SIP, LiveKit un G.711
Šajā lapā
Atjaunināts 2026. gada 3. novembrī, pamatojoties uz xAI SIP Phone Calls rokasgrāmatu, Speech to Speech lapu un Phone Voice Agent paraugpiemēru. xAI var atbildēt uz zvaniem uz jūsu numuru tieši (tiešais SIP, parakstīts tīmekļa āķis, pāradresācija, atlikšana, DTMF taustiņi), kā arī izmantojot tiltu caur jūsu pašu serveri. Avoti: SIP Phone Calls · Speech to Speech · Phone Voice Agent.
Savieno Voice Agent API ar telefona tīklu
Voice Agent API spēj apstrādāt telefona zvanus: tavi klienti zvana uz parastu numuru un sarunājas ar tavu Grok aģentu. Tev ir pieejami trīs ceļi, lai to īstenotu – sākot no visintegrētākā līdz viselastīgākajam.
1. ceļš: tiešais SIP ar xAI
Šajā režīmā xAI pats atbild uz zvanu. Zvans nonāk xAI SIP infrastruktūrā, kas tevi informē, izmantojot tīmekļa āķi; tava lietotne pievienojas zvanam, izmantojot WebSocket, un vada aģentu.
- Reģistrē numuru. Deklarē xAI „Direct SIP” numuru kopā ar tīmekļa āķa adresi, kas saņems ienākošos zvanus. Ja izmanto savu numuru, norādi
origin: "byo_trunk": xAI nepiedāvā numurus, izmantojot API. Atbildē tiek atgriezts parakstīšanas noslēpums (signing secret), kas tiek parādīts tikai vienreiz, tāpēc saglabā to savā noslēpumu glabātuvē. - Novirzi savu operatoru. Konfigurē savu operatoru vai PBX, lai tas nosūtītu zvanus uz
sip:{number}@sip.voice.x.ai. xAI pieņem SIP signalizāciju caur TLS portā 5061 vai caur TCP/UDP portā 5060; dod priekšroku;transport=tls, ja tavs operators to atbalsta. - Saņem tīmekļa āķi. Par katru zvanu xAI nosūta parakstītu
realtime.call.incomingtīmekļa āķi. Pārbaudi galveneswebhook-id,webhook-timestampunwebhook-signature, izmantojot parakstīšanas noslēpumu, pēc tam nolasīdata.call_id. - Pievienojies zvanam. Atver
wss://api.x.ai/v1/realtime?call_id={call_id}, izmantojot savu API atslēgu (epemērie žetoni SIP sesijai netiek pieņemti), nosūtisession.updateun pēc tamresponse.create, kad aģentam jārunā.
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
Kad savienojums ir izveidots, sesija uzvedas tāpat kā jebkura cita balss sesija: xAI pārraida zvanītāja audio un atskaņo aģenta atbildi, neveicot skaņas pārraidi caur tavu serveri.
Pāradresācija vai atlikšana
Līniju kontrolē divi REST izsaukumi. POST /v1/realtime/calls/{call_id}/refer ar target_uri formātā tel: vai sip: pāradresē zvanītāju; pieprasījums gaida pāradresācijas iznākumu. 200 ar tukšu ķermeni nozīmē, ka galamērķis atbildēja; 502 satur SIP noraidījuma kodu, bet 504 signalizē par taimautu. Pēc kļūmes sesija paliek atvērta, un aģents var turpināt runāt: tava ziņa ir nolasīt atbildi un, ja nepieciešams, likt aģentam izskaidrot radušos problēmu. POST /v1/realtime/calls/{call_id}/hangup pārtrauc zvanu.
Taustiņu ievade (DTMF)
SIP sesijā zvanītāja nospiestie taustiņi tiek buferizēti un nodoti modelim kā teksts, tiklīdz zvanītājs nospiež #, pēc 2,5 sekundēm bez jauna taustiņa nospiešanas vai tiklīdz viņš sāk runāt. Tavs klients saņem vienu input_audio_buffer.dtmf_event_received notikumu par katru taustiņu, lai tu varētu veikt uzskaiti. Lai ļautu aģentam pašam nospiest taustiņus, piemēram, lai navigētu cita servisa telefona izvēlnē, pievieno tam rīku {"type": "function", "name": "send_dtmf"} bez parametriem: API nodrošina shēmu un nosūta signālus, un tev uz šiem funkciju izsaukumiem nav jāatbild. Šie notikumi pastāv tikai SIP sesijā.
Dokumentētie operatori
xAI rokasgrāmata soli pa solim izskaidro iestatīšanu četriem operatoriem (Twilio ar Elastic SIP Trunking un iespējotu zvanu pāradresāciju, ja veic pāradresāciju; Bandwidth; Telnyx; un Plivo), kā arī jebkuram operatoram, kontaktpunktam vai PBX, kas spēj atvērt SIP maršrutu uz tava numura adresi. Kodeka ziņā Telnyx piemērs prasa iespējot vismaz G.711 μ-law, G.711 A-law vai G.722.
2. ceļš: tilts caur tavu serveri
Ja vēlies saglabāt kontroli pār audio plūsmu, tavs serveris saņem zvana audio un pārraida to uz parastu WebSocket sesiju. Tāda ir xAI paraugpiemēra Phone Voice Agent arhitektūra: Twilio straumē zvana audio μ-law formātā, izmantojot savu Media Streams, un serveris to nodod API tālāk bez konvertēšanas abos virzienos.
# 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 natīvi pieņem abus G.711 variantus, tādējādi izvairoties no transkodēšanas: audio/pcmu (μ-law, Ziemeļamerikas un Japānas standarts) un audio/pcma (A-law, standarts Eiropā un lielākajā daļā citu valstu), abus ar 8000 Hz.
{
"audio": {
"input": {"format": {"type": "audio/pcma", "rate": 8000}},
"output": {"format": {"type": "audio/pcma", "rate": 8000}}
}
}
DTMF taustiņi un REST pāradresācijas un atlikšanas izsaukumi pieder tiešajam SIP ceļam: tiltā tos apstrādā tavs operators.
3. ceļš: reāllaika ietvars
xAI dokumentācija uzskaita divas gatavas integrācijas: LiveKit Agents un Pipecat. Tās apstrādā reāllaika transportu (WebRTC, istabas, zvanu maršrutēšanu) un pieslēdz Grok balss aģentu īstajā vietā, kas ļauj komandām izvairīties no telekomunikāciju slāņa veidošanas no nulles.
Ražošanas vidē
Apstrādā klusuma brīžus. Telefonā zvanītājs, kurš klusē, atstāj līniju mirušu. turn_detection.idle_timeout_ms liek aģentam sazināties ar zvanītāju pēc tavā izvēlēta ilguma klusuma (6. nodarbība).
Turpini sarunu jaunā zvanā. Sesijas atsākšana darbojas arī caur SIP: pirmajā zvanā iespējo resumption.enabled un saglabā tā call_id. Kad klients atzvana, atver wss://api.x.ai/v1/realtime?call_id={new_call_id}&conversation_id={previous_call_id} un atkārtoti nosūti to pašu session.update. Vēsture beidzas pēc 30 minūtēm bezdarbības.
Ievēro noteikumus. Paziņo zvanītājiem, ka viņi runā ar AI, un, ja ieraksti zvanus, paziņo to sarunas sākumā. Attiecībā uz veselības datiem xAI norāda, ka BAA (Business Associate Agreement) var parakstīt pēc anketas aizpildīšanas.
Mēri savu latentumu. Kavējums, ko uztver zvanītāji, veidojas no telefona tīkla, tava tilta (ja tāds ir) un atbildes ģenerēšanas laika. Mēri to no gala līdz galam reālos zvanos un nodroši, ka funkcijas, ko aģents izsauc sarunas laikā, darbojas ātri.
Galvenās atziņas
- Izmantojot tiešo SIP, xAI atbild uz tava numura zvaniem, informē tevi ar parakstītu
realtime.call.incomingtīmekļa āķi, un tu pievienojies zvanam caurwss://api.x.ai/v1/realtime?call_id=… referpāradresē zvanu (iznākums tiek atgriezts HTTP atbildē), bethangupto pārtrauc- DTMF taustiņi sasniedz modeli un tiek reģistrēti caur
input_audio_buffer.dtmf_event_received; rīkssend_dtmfļauj aģentam nospiest taustiņus - Tiltā caur tavu serveri natīvais G.711 (
audio/pcmu,audio/pcma) izvairās no transkodēšanas - LiveKit Agents un Pipecat ir integrācijas, ko uzskaita xAI