Telefonija: SIP, LiveKit ir G.711
Šiame puslapyje
Atnaujinta 2026 m. lapkričio 3 d., remiantis xAI SIP Phone Calls vadovu, Speech to Speech puslapiu ir Phone Voice Agent pavyzdžiu iš receptų knygos. xAI gali atsakyti į skambučius tiesiai į jūsų numerį (tiesioginis SIP, pasirašytas „webhook“, peradresavimas, pakabinimas, DTMF klavišai), kartu naudodamas tiltą per jūsų paties serverį. Šaltiniai: SIP Phone Calls · Speech to Speech · Phone Voice Agent.
Prijunkite Voice Agent API prie telefono tinklo
Voice Agent API gali priimti telefono skambučius: jūsų klientai renka įprastą numerį ir kalbasi su jūsų Grok agentu. Yra trys keliai tai pasiekti – nuo labiausiai integruoto iki lanksčiausio.
1 kelias: tiesioginis SIP su xAI
Šiuo režimu skambutį priima pats xAI. Skambutis patenka į xAI SIP infrastruktūrą, kuri jus informuoja per „webhook“; jūsų programa prisijungia prie skambučio per „WebSocket“ ir valdo agentą.
- Įregistruokite numerį. Deklaruokite „Direct SIP“ numerį xAI sistemoje kartu su „webhook“ adresu, į kurį bus siunčiami gaunami skambučiai. Jei naudojate savo turimą numerį, naudokite
origin: "byo_trunk": xAI per API numerių neteikia. Atsakyme gausite pasirašymo slaptąjį raktą, kuris grąžinamas tik vieną kartą, todėl saugiai jį įsisaugokite savo slapčių saugykloje. - Nukreipkite savo operatorių. Sukonfigūruokite savo ryšių operatorių arba PBX, kad siųstų skambučius adresu
sip:{number}@sip.voice.x.ai. xAI priima SIP signalizaciją per TLS 5061 porte arba per TCP/UDP 5060 porte; jei jūsų operatorius palaiko, pirmenybę teikite;transport=tls. - Gaukite „webhook“ pranešimą. Kiekvieno skambučio metu xAI siunčia pasirašytą
realtime.call.incoming„webhook“ pranešimą. Patikrinkite antrašteswebhook-id,webhook-timestampirwebhook-signaturenaudodami pasirašymo slaptąjį raktą, tada nuskaitykitedata.call_id. - Prisijunkite prie skambučio. Atidarykite
wss://api.x.ai/v1/realtime?call_id={call_id}naudodami savo API raktą (laikini žetonai SIP sesijoms netinka), išsiųskitesession.update, o tadaresponse.create, kai agentas turi pradėti kalbėti.
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
Prisijungus, sesija elgiasi kaip bet kuri kita balso sesija: xAI perduoda skambinančiojo garsą ir atkuria agento atsakymą jam, nenešdamas garso per jūsų serverį.
Peradresavimas arba pakabinimas
Liniją valdo du REST užklausos tipai. POST /v1/realtime/calls/{call_id}/refer su target_uri formatu tel: arba sip: peradresuoja skambinantįjį; užklausa laukia peradresavimo rezultato. 200 statusas su tuščiu kūnu reiškia, kad gavėjas atsakė; 502 perduoda SIP atmetimo kodą, o 504 signalizuoja laiko limito viršijimą. Nepavykus, sesija lieka atvira ir agentas gali toliau kalbėti: jūsų užduotis – nuskaityti atsakymą ir prireikus paprašyti agento paaiškinti sutrikimą. POST /v1/realtime/calls/{call_id}/hangup nutraukia skambutį.
Klaviatūros įvestis (DTMF)
SIP sesijos metu skambinančiojo paspausti klavišai yra buferizuojami ir perduodami modeliui kaip tekstas, kai tik paspaudžiamas #, praėjus 2,5 sekundės be naujo paspaudimo arba kai tik jis pradeda kalbėti. Jūsų klientas gauna vieną input_audio_buffer.dtmf_event_received įvykį kiekvienam klavišui, todėl galite vesti žurnalą. Norėdami leisti agentui pačiam spausti klavišus, pavyzdžiui, norint naršyti kitos tarnybos telefono meniu, pridėkite {"type": "function", "name": "send_dtmf"} prie jo įrankių be parametrų: API pateikia schemą ir siunčia tonus, o jūs neturite atsakyti į šiuos funkcijų kvietimus. Šie įvykiai egzistuoja tik SIP sesijoje.
Dokumentuoti operatoriai
xAI vadove aprašyta sąranka keturiems operatoriams („Twilio“ su įjungtu „Elastic SIP Trunking“ ir skambučių peradresavimu magistralėje, jei peradresuojate skambučius; „Bandwidth“; „Telnyx“; ir „Plivo“) bei bet kuriam operatoriui, kontaktų centrui ar PBX, galinčiam atidaryti SIP maršrutą į jūsų numerio adresą. Kodeko požiūriu „Telnyx“ pavyzdyje prašoma įjungti bent G.711 μ-law, G.711 A-law arba G.722.
2 kelias: tiltas per jūsų serverį
Jei norite išlaikyti garso srauto kontrolę, jūsų serveris priima skambučio garsą ir perduoda jį į įprastą „WebSocket“ sesiją. Tai yra xAI receptų knygos pavyzdžio Phone Voice Agent architektūra: „Twilio“ perduoda skambučio garsą μ-law formatu per savo „Media Streams“, o serveris jį perduoda API tokį patį, be konvertavimo, abiem kryptimis.
# 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 savaime priima abu G.711 variantus, todėl išvengiama bet kokio transkodavimo: audio/pcmu (μ-law, Šiaurės Amerikos ir Japonijos standartas) ir audio/pcma (A-law, Europos ir daugumos kitų šalių standartas), abu 8000 Hz dažniu.
{
"audio": {
"input": {"format": {"type": "audio/pcma", "rate": 8000}},
"output": {"format": {"type": "audio/pcma", "rate": 8000}}
}
}
DTMF klavišai ir REST peradresavimo bei pakabinimo užklausos priklauso tiesioginio SIP keliui: tilto atveju jais rūpinasi jūsų operatorius.
3 kelias: realiuoju laiku veikianti sistema
xAI dokumentacijoje išvardyti du paruošti integracijos sprendimai: „LiveKit Agents“ ir „Pipecat“. Jie tvarko realiojo laiko transportą (WebRTC, kambarius, skambučių maršrutizavimą) ir tinkamoje vietoje prijungia Grok balso agentą, taip sutaupydami komandai, kuri nenori kurti telefonijos sluoksnio nuo nulio, daug laiko.
Naudojimas gamyboje
Valdykite tylos momentus. Telefone skambinantysis, nutilęs, palieka „negyvą“ liniją. turn_detection.idle_timeout_ms priverčia agentą pasitikrinti ryšį su skambinančiuoju po jūsų pasirinktos trukmės tylos (6 pamoka).
Pratęskite pokalbį naujo skambučio metu. Sesijos atnaujinimas veikia ir per SIP: pirmojo skambučio metu įjunkite resumption.enabled ir išsaugokite jo call_id. Kai klientas perskambins, atidarykite wss://api.x.ai/v1/realtime?call_id={new_call_id}&conversation_id={previous_call_id} ir vėl išsiųskite tą patį session.update. Istorija galioja 30 minučių po neveiklos.
Laikykitės taisyklių. Informuokite skambinančiuosius, kad jie kalbasi su DI, o jei įrašinėjate pokalbius, apie tai praneškite pokalbio pradžioje. Dėl sveikatos duomenų xAI nurodo, kad BAA (Business Associate Agreement) gali būti pasirašytas po anketos užpildymo.
Matuokite savo delsą. Skambinančiojo suvokiama delsa susideda iš telefono tinklo, jūsų tilto (jei jį naudojate) ir atsakymo generavimo laiko. Matuokite ją nuo galo iki galo realių skambučių metu ir užtikrinkite, kad agento pokalbio metu kviečiamos funkcijos veiktų greitai.
Svarbiausi punktai
- Naudodami tiesioginį SIP, xAI atsako į jūsų numerį, informuoja jus pasirašytu
realtime.call.incoming„webhook“ pranešimu, o jūs prisijungiate prie skambučio perwss://api.x.ai/v1/realtime?call_id=… referperadresuoja skambutį (rezultatas grąžinamas HTTP atsakyme), ohangupjį nutraukia- DTMF klavišai pasiekia modelį ir registruojami per
input_audio_buffer.dtmf_event_received; įrankissend_dtmfleidžia agentui spausti klavišus - Tilte per jūsų serverį natūralus G.711 (
audio/pcmu,audio/pcma) išvengia transkodavimo - „LiveKit Agents“ ir „Pipecat“ yra xAI išvardytos integracijos