Telefonija: SIP, LiveKit i G.711
Na ovoj stranici
Ažurirano 3. studenoga 2026., na temelju xAI vodiča SIP Phone Calls, stranice Speech to Speech i primjera iz kuharice Phone Voice Agent. xAI može sam odgovarati na pozive na tvoj broj (izravni SIP, potpisani webhook, prosljeđivanje, prekid veze, DTMF tipke), uz most preko tvog vlastitog poslužitelja. Izvori: SIP Phone Calls · Speech to Speech · Phone Voice Agent.
Povezivanje Voice Agent API-ja s telefonskom mrežom
Voice Agent API može primati telefonske pozive: tvoji klijenti biraju običan broj i razgovaraju s tvojim Grok agentom. Tri su puta do toga, od najintegriranijeg do najfleksibilnijeg.
Put 1: izravni SIP s xAI-jem
U ovom načinu rada xAI sam odgovara na poziv. Poziv završava na xAI-jevoj SIP infrastrukturi, koja te obavještava putem webhooka; tvoja aplikacija se pridružuje pozivu preko WebSocketa i upravlja agentom.
- Registriraj broj. Prijavi broj „Izravni SIP“ (Direct SIP) kod xAI-ja, zajedno s adresom webhooka koja će primati dolazne pozive. Za broj koji posjeduješ koristi
origin: "byo_trunk": xAI ne dodjeljuje brojeve putem API-ja. Odgovor sadrži tajnu za potpisivanje koja se vraća samo jednom, pa je pohrani u svoj trezor tajni. - Usmjeri svog operatera. Konfiguriraj svog operatera ili PBX da šalje pozive na
sip:{number}@sip.voice.x.ai. xAI prihvaća SIP signalizaciju preko TLS-a na portu 5061 ili TCP/UDP na portu 5060; preferiraj;transport=tlskada ga tvoj operater podržava. - Primi webhook. Za svaki poziv xAI šalje potpisani webhook
realtime.call.incoming. Potvrdi zaglavljawebhook-id,webhook-timestampiwebhook-signaturepomoću tajne za potpisivanje, zatim pročitajdata.call_id. - Pridruži se pozivu. Otvori
wss://api.x.ai/v1/realtime?call_id={call_id}sa svojim API ključem (privremeni tokeni nisu prihvaćeni za SIP sesiju), pošaljisession.update, a zatimresponse.createkada agent treba progovoriti.
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
Nakon povezivanja, sesija se ponaša kao bilo koja druga glasovna sesija: xAI prosljeđuje audio pozivatelja i reproducira agenta natrag njemu, bez da tvoj poslužitelj prenosi zvuk.
Prosljeđivanje ili prekid veze
Dva REST poziva upravljaju linijom. POST /v1/realtime/calls/{call_id}/refer, s target_uri u obliku tel: ili sip:, prosljeđuje pozivatelja; zahtjev čeka ishod prosljeđivanja. 200 s praznim tijelom znači da je odredište odgovorilo; 502 nosi SIP kod odbijanja, a 504 signalizira istek vremena. Nakon neuspjeha sesija ostaje otvorena i agent može nastaviti razgovor: na tebi je da pročitaš odgovor i, ako je potrebno, navedeš agenta da objasni problem. POST /v1/realtime/calls/{call_id}/hangup završava poziv.
Unos s tipkovnice (DTMF)
Na SIP sesiji tipke koje pozivatelj pritisne međuspremaju se, a zatim prosljeđuju modelu kao tekst čim pozivatelj pritisne #, nakon 2,5 sekunde bez nove tipke ili čim počne govoriti. Tvoj klijent prima jedan događaj input_audio_buffer.dtmf_event_received po tipki, tako da možeš voditi evidenciju. Da bi agent sam pritiskao tipke, primjerice za navigaciju kroz telefonski izbornik druge usluge, dodaj {"type": "function", "name": "send_dtmf"} u njegove alate, bez parametara: API pruža shemu i šalje tonove, a ti ne smiješ odgovarati na ove pozive funkcija. Ovi događaji postoje samo na SIP sesiji.
Dokumentirani operateri
xAI vodič prolazi kroz postavke za četiri operatera (Twilio, s uključenim Elastic SIP Trunkingom i prosljeđivanjem poziva na trupu ako prosljeđuješ pozive; Bandwidth; Telnyx; i Plivo) te za bilo kojeg operatera, kontakt centar ili PBX koji može otvoriti SIP rutu do adrese tvog broja. Što se tiče kodeka, Telnyx primjer traži da omogućiš barem G.711 μ-law, G.711 A-law ili G.722.
Put 2: most preko tvog vlastitog poslužitelja
Ako želiš zadržati kontrolu nad audio tokom, tvoj poslužitelj prima audio poziva i prosljeđuje ga redovnoj WebSocket sesiji. To je arhitektura xAI-jevog primjera Phone Voice Agent iz kuharice: Twilio strimuje audio poziva u μ-law formatu kroz svoje Media Streams, a poslužitelj ga prosljeđuje API-ju kakav jest, bez konverzije, u oba smjera.
# 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 izvorno prihvaća obje varijante G.711, čime se izbjegava transkodiranje: audio/pcmu (μ-law, standard u Sjevernoj Americi i Japanu) i audio/pcma (A-law, standard u Europi i većini drugih zemalja), oba na 8000 Hz.
{
"audio": {
"input": {"format": {"type": "audio/pcma", "rate": 8000}},
"output": {"format": {"type": "audio/pcma", "rate": 8000}}
}
}
DTMF tipke te REST pozivi za prosljeđivanje i prekid veze pripadaju putu izravnog SIP-a: u mostu ih obrađuje tvoj operater.
Put 3: okvir za rad u stvarnom vremenu
xAI dokumentacija navodi dvije gotove integracije: LiveKit Agents i Pipecat. One rukuju prijenosom u stvarnom vremenu (WebRTC, sobe, usmjeravanje poziva) i uključuju Grok glasovnog agenta na pravom mjestu, što štedi timove koji ne žele graditi telefonski sloj od nule.
U proizvodnji
Rukuj tišinama. Na telefonu, pozivatelj koji utihne ostavlja mrtvu liniju. turn_detection.idle_timeout_ms navodi agenta da se javi pozivatelju nakon tišine trajanja koje odabereš (lekcija 6).
Nastavi razgovor na novom pozivu. Nastavak sesije također radi preko SIP-a: omogući resumption.enabled na prvom pozivu i zadrži njegov call_id. Kada klijent ponovno nazove, otvori wss://api.x.ai/v1/realtime?call_id={new_call_id}&conversation_id={previous_call_id} i ponovno pošalji isti session.update. Povijest istječe nakon 30 minuta neaktivnosti.
Slijedi pravila. Obavijesti pozivatelje da razgovaraju s AI-jem i, ako snimaš pozive, reci to na početku. Za zdravstvene podatke, xAI navodi da se BAA (Business Associate Agreement) može potpisati nakon upitnika.
Izmjeri svoju latenciju. Kašnjenje koje pozivatelji percipiraju zbraja telefonsku mrežu, tvoj most (ako ga imaš) i generiranje odgovora. Izmjeri ga od kraja do kraja na stvarnim pozivima i osiguraj da funkcije koje agent poziva tijekom razgovora budu brze.
Ključne točke
- S izravnim SIP-om, xAI odgovara na tvoj broj, obavještava te potpisanim webhookom
realtime.call.incoming, a ti se pridružuješ pozivu putemwss://api.x.ai/v1/realtime?call_id=… referprosljeđuje poziv (ishod se vraća u HTTP odgovoru), ahangupga završava- DTMF tipke stižu do modela i bilježe se kroz
input_audio_buffer.dtmf_event_received; alatsend_dtmfomogućuje agentu pritiskanje tipki - U mostu preko tvog poslužitelja, izvorni G.711 (
audio/pcmu,audio/pcma) izbjegava transkodiranje - LiveKit Agents i Pipecat integracije su koje xAI navodi