Telefonie: SIP, LiveKit și G.711
Pe această pagină
Actualizat la 3 noiembrie 2026, pe baza ghidului xAI SIP Phone Calls, a paginii Speech to Speech și a exemplului din cookbook-ul Phone Voice Agent. xAI poate prelua apeluri direct pe numărul dumneavoastră (SIP direct, webhook semnat, transfer, închidere apel, taste DTMF), alături de o soluție de punte prin propriul server. Surse: SIP Phone Calls · Speech to Speech · Phone Voice Agent.
Conectarea Voice Agent API la rețeaua telefonică
Voice Agent API poate prelua apeluri telefonice: clienții dumneavoastră formează un număr obișnuit și conversează cu agentul Grok. Există trei căi pentru a realiza acest lucru, de la cea mai integrată la cea mai flexibilă.
Calea 1: SIP direct cu xAI
În acest mod, xAI preia apelul direct. Apelul ajunge pe infrastructura SIP a xAI, care vă notifică prin webhook; aplicația dumneavoastră se alătură apelului prin WebSocket și gestionează agentul.
- Înregistrați numărul. Declarați un număr „Direct SIP“ la xAI, împreună cu adresa webhook-ului care va primi apelurile primite. Pentru un număr pe care îl dețineți deja, utilizați
origin: "byo_trunk": xAI nu furnizează numere prin API. Răspunsul conține un secret de semnătură, returnat o singură dată, așa că stocați-l în seiful dumneavoastră de secrete. - Configurați operatorul. Configurați operatorul de telefonie sau PBX-ul pentru a direcționa apelurile către
sip:{number}@sip.voice.x.ai. xAI acceptă semnalizarea SIP peste TLS pe portul 5061 sau TCP/UDP pe portul 5060; preferați;transport=tlsdacă operatorul dumneavoastră suportă acest lucru. - Primiți webhook-ul. Pentru fiecare apel, xAI trimite un webhook semnat
realtime.call.incoming. Verificați anteturilewebhook-id,webhook-timestampșiwebhook-signaturefolosind secretul de semnătură, apoi citițidata.call_id. - Alăturați-vă apelului. Deschideți conexiunea
wss://api.x.ai/v1/realtime?call_id={call_id}cu cheia dumneavoastră API (token-urile efemere nu sunt acceptate pentru o sesiune SIP), trimitețisession.update, apoiresponse.createcând agentul trebuie să vorbească.
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
Odată conectat, sesiunea se comportă ca orice altă sesiune vocală: xAI retransmite audio-ul apelantului și îi redă vocea agentului, fără ca serverul dumneavoastră să transporte vreun sunet.
Transfer sau închidere apel
Două apeluri REST controlează linia. POST /v1/realtime/calls/{call_id}/refer, cu un target_uri în format tel: sau sip:, transferă apelantul; cererea așteaptă rezultatul transferului. Un cod 200 cu un corp gol indică faptul că destinația a răspuns; un cod 502 conține codul de respingere SIP, iar un cod 504 semnalează o expirare a timpului de așteptare (timeout). După o eroare, sesiunea rămâne deschisă, iar agentul poate continua să vorbească: depinde de dumneavoastră să citiți răspunsul și, dacă este necesar, să instruiți agentul să explice problema. POST /v1/realtime/calls/{call_id}/hangup închide apelul.
Input de la tastatură (DTMF)
Într-o sesiune SIP, tastele apăsate de apelant sunt stocate în tampon și apoi transmise modelului sub formă de text imediat ce apelantul apasă #, după 2,5 secunde fără o nouă apăsare de tastă sau imediat ce începe să vorbească. Clientul dumneavoastră primește un eveniment input_audio_buffer.dtmf_event_received pentru fiecare tastă, permițându-vă să păstrați un istoric. Pentru a permite agentului să apese taste singur, de exemplu pentru a naviga prin meniul telefonic al altui serviciu, adăugați {"type": "function", "name": "send_dtmf"} la instrumentele sale, fără parametri: API-ul furnizează schema și trimite tonurile, iar dumneavoastră nu trebuie să răspundeți la aceste apeluri de funcție. Aceste evenimente există doar într-o sesiune SIP.
Operatori documentați
Ghidul xAI detaliază configurarea pentru patru operatori (Twilio, cu Elastic SIP Trunking și transfer de apel activat pe tronson dacă efectuați transferuri; Bandwidth; Telnyx; și Plivo) și pentru orice operator, centru de contact sau PBX care poate deschide o rută SIP către adresa numărului dumneavoastră. Din perspectiva codec-ului, exemplul Telnyx vă cere să activați cel puțin G.711 μ-law, G.711 A-law sau G.722.
Calea 2: O punte prin propriul server
Dacă doriți să păstrați controlul asupra fluxului audio, serverul dumneavoastră primește audio-ul apelului și îl retransmite către o sesiune WebSocket obișnuită. Aceasta este arhitectura exemplului Phone Voice Agent din cookbook-ul xAI: Twilio transmite audio-ul apelului în μ-law prin Media Streams, iar serverul îl transmite către API exact așa cum este, fără conversie, în ambele sensuri.
# 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-ul acceptă nativ ambele variante G.711, evitând astfel orice transcodare: audio/pcmu (μ-law, standardul în America de Nord și Japonia) și audio/pcma (A-law, standardul în Europa și majoritatea celorlalte țări), ambele la 8000 Hz.
{
"audio": {
"input": {"format": {"type": "audio/pcma", "rate": 8000}},
"output": {"format": {"type": "audio/pcma", "rate": 8000}}
}
}
Tastele DTMF și apelurile REST de transfer și închidere aparțin căii SIP direct: într-o soluție de tip punte, operatorul dumneavoastră le gestionează.
Calea 3: Un framework în timp real
Documentația xAI listează două integrări gata făcute: LiveKit Agents și Pipecat. Acestea gestionează transportul în timp real (WebRTC, camere, rutarea apelurilor) și conectează agentul vocal Grok în punctul potrivit, scutind echipele care nu doresc să construiască un strat de telefonie de la zero de această sarcină.
În producție
Gestionați silențiile. La telefon, un apelant care tace lasă linia moartă. turn_detection.idle_timeout_ms face ca agentul să verifice statusul apelantului după o perioadă de liniște de durata aleasă de dumneavoastră (lecția 6).
Reluați o conversație la un apel nou. Reluarea sesiunii funcționează și prin SIP: activați resumption.enabled la primul apel și păstrați call_id-ul său. Când clientul sună din nou, deschideți wss://api.x.ai/v1/realtime?call_id={new_call_id}&conversation_id={previous_call_id} și trimiteți din același session.update. Istoricul expiră după 30 de minute de inactivitate.
Respectați regulile. Informați apelantii că vorbesc cu un AI și, dacă înregistrați apelurile, menționați acest lucru la început. Pentru datele privind sănătatea, xAI indică faptul că un BAA (Business Associate Agreement) poate fi semnat după completarea unui chestionar.
Măsurați latența. Întârzierea percepută de apelant este suma latenței rețelei telefonice, a punții dumneavoastră (dacă aveți una) și a generării răspunsului. Măsurați-o cap-la-cap pe apeluri reale și asigurați-vă că funcțiile pe care agentul le apelează în timpul conversației sunt rapide.
Puncte cheie
- Cu SIP direct, xAI răspunde la numărul dumneavoastră, vă notifică printr-un webhook semnat
realtime.call.incoming, iar dumneavoastră vă alăturați apelului prinwss://api.x.ai/v1/realtime?call_id=… refertransferă apelul (rezultatul revine în răspunsul HTTP), iarhangupîl închide- Tastele DTMF ajung la model și sunt jurnalizate prin
input_audio_buffer.dtmf_event_received; instrumentulsend_dtmfpermite agentului să apese taste - Într-o punte prin serverul dumneavoastră, G.711 nativ (
audio/pcmu,audio/pcma) evită transcodarea - LiveKit Agents și Pipecat sunt integrările listate de xAI